Docs For organizations
Withdrawal and delegations
Withdraw an issuer with a committed result and a stated race bound, understand suspension, and delegate subdomains to other organizations.
Withdrawing an issuer
POST /v1/issuer-bindings/{id}/withdraw (owner or issuer administrator, human, step-up):
{"expected_version": 4, "reason": "Decommissioning the EU agent fleet"}reason is required (1 to 2000 characters). It goes to the audit log only and is never public. expected_version must equal the binding's current version, otherwise 409.
Withdrawal works in any live state. A binding that was never published (draft, pending_review) is closed and its trust domain becomes free again. A published binding (active, suspended) becomes withdrawn, which is terminal, with a public binding.withdrawn event, all in one commit. A rotation in flight is withdrawn with it.
The answer is sent only after the commit:
{"status": "withdrawn", "committed_at": "2026-10-05T12:00:00.000Z", "assertion_bound_seconds": 330, "binding": { "...": "..." }}From the next authoritative read on, /v1/resolve returns status: "withdrawn" with no assertion. An assertion signed from a read taken just before the commit stays valid until its own exp, at most 300 seconds after that read, and verifiers allow 30 seconds of clock skew. So 330 seconds after committed_at is the worst case for any relying party.
Withdrawal stops the directory's endorsement. It does not revoke SVIDs your issuer already minted; short SVID lifetimes and revocation on the SPIRE side remain your responsibility. The served version's bundle stays fetchable at its URL, but holding it no longer means anything is endorsed.
Suspension
A binding is suspended when a claim backing it stops being verified: its own claim, or for a delegated binding the delegation's parent claim (a dispute, a lapsed DNS recheck or an expired authority, for example). Suspended bindings resolve as status: "suspended" with no assertion, and a public binding.suspended event is written.
| Then | What happens |
|---|---|
| Every backing claim is verified again within 30 days | The binding resumes automatically, with a public binding.resumed event |
| 30 days pass first | Its own claim lapsed: the binding is withdrawn for good. The parent claim lapsed: the delegation is revoked. |
| Its own claim is rejected, withdrawn or expired | Withdrawn immediately, in the same commit. An appeal does not revive it. |
expires_at passes |
Expired (terminal), with a public binding.expired event |
A dispute or review that lasts longer than 30 days therefore permanently withdraws the bindings that depend on it; the organization then has to register and prove the issuer again.
Delegations
A delegation lets your organization authorize another organization to operate a subdomain of your verified claim, for example eu.payments.example.com for a regional subsidiary.
Create one
POST /v1/delegations, by the parent claim's owner with step-up:
{
"parent_claim_id": "clm_4b7e1h5k8n2q6t9w3z0c4f7j1m",
"child_domain": "eu.payments.example.com",
"recipient_organization_id": "org_2c5f8j1m4p7s0v3y6b9e2h5k8n",
"scope": ["/agent/checkout"],
"actions": ["authorize_issuer"],
"expires_at": "2027-06-30T00:00:00Z"
}Each rule below is reported as a field_errors entry whose message is the reason code:
| Rule | Reason code |
|---|---|
The parent claim is verified and its reviewed actions include delegate |
403 or 422 |
| The child is a strict DNS descendant of the parent's domain | child_not_strict_descendant |
Actions are authorize_issuer and/or manage_domain; delegate is refused |
redelegation_not_supported |
| Actions are a subset of what the parent holds | action_escalation |
| The scope is within the parent's scope | scope_escalation |
| Expiry is more than 1 minute and at most 1 year ahead, and not after the parent's representative authority | expiry_beyond_parent |
| No cycles | delegation_cycle |
| No other organization holds a more specific verified claim covering the child | child_under_more_specific_claim |
You cannot delegate to yourself. At most 10 delegations per organization per hour; a child that already has a pending or active delegation answers 409.
Activation
The delegation starts as pending_review. It becomes active when both the recipient organization's owner accepts it (POST /v1/delegations/{id}/accept, step-up, with expected_version) and an internal reviewer approves it, whichever comes second. A public delegation.activated event follows. The recipient can then register issuers under the child domain, limited to the delegated scope and actions.
Control of a child grants no authority over the parent or its siblings, and the directory never infers common ownership from suffixes, redirects, shared hosting or shared certificates.
Withdraw one
POST /v1/delegations/{id}/withdraw, by the parent's owner or the recipient's owner, with step-up and expected_version. In one commit the delegation becomes withdrawn and every binding that depends on it leaves service: published bindings are suspended (each with a public event) and unpublished ones are withdrawn. A delegation also ends as expired at its expiry or revoked when the parent claim stays unverified for more than 30 days.