This is the documentation of iya-sts 1.0.0. The latest is 1.1.0.

Management API

Every answer is checked against the model shown here before it is sent, and no answer carries a member its model does not list. A member shown as any JSON is one whose shape belongs to somebody else, and says whose. .{key} is a key that is data, and [] an element of a list.

A refusal

Unless an operation below says otherwise, any status it does not list answers this:

Member Type Required What it is
error string    
error_description string    
errors list    
errors[] string    
message string    
ok boolean    
status integer    
why string    

GET /admin-api/spiffe

getSpiffe

The trust domain: its authorities, its bundle, its listeners

What this service is as a SPIFFE issuing authority. The X.509 and JWT authorities (the ACTIVE one first, with the retired ones that are still published behind it), the bundle path and its sequence, every federated trust domain, and whether each of the four gRPC listeners actually bound — which nothing else can tell you, because neither this API nor GET /admin/sts-metadata can see a socket, and workloadAttestation: what the Workload API’s Unix socket attests, and under tcp whether its TCP port is served — in product only where spiffe.workloadTcpSourceAuthenticated declares the network authenticates source addresses, on a named address (#166).

The reply also carries authentication: whether the SPIRE Server API is enforcing mutual TLS, which identities are administrators, and the whole per-method authorization table, which is SPIRE’s own policy_data.json row for row.

A Workload API caller on the Unix socket is attested by the workload attestors spiffe.workloadAttestors names; one over TCP is identified only by the transport, the endpoint and its address, which is why a product realm refuses a registration entry selecting nothing but the transport and endpoint. An agent’s attestation is verified by the attestor its type names or refused (#40, 2026-09-21). Where the SPIRE Server API authenticates nobody, any caller that reaches its port can create a registration entry granting any identity here. GET /spiffe carries the full list of what is and is not checked.

No private key is in this reply. The authority CERTIFICATE is published, as GET /tls/server-certificate publishes that one.

Mirrors GET /admin/cert-issuance on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The trust domain, its authorities, its federated bundles and its listeners.

Member Type Required What it is
authentication object    
authentication.acceptAssertedSelectors boolean    
authentication.adminIds list    
authentication.adminIds[] string    
authentication.assertedSelectorHeader string    
authentication.attestWorkloads boolean    
authentication.bootstrapping string    
authentication.credentialStatusNote string    
authentication.enforced boolean    
authentication.entities list    
authentication.entities[].id string    
authentication.entities[].label string    
authentication.entities[].what string    
authentication.identityNote string    
authentication.policy list    
authentication.policy[].allow list    
authentication.policy[].allow[] string    
authentication.policy[].method string    
authentication.trustLocalSocket boolean    
authentication.what string    
authorities object    
authorities.chainSubjects list    
authorities.chainSubjects[] string    
authorities.jwt list    
authorities.jwt[].active boolean    
authorities.jwt[].alg string, or null    
authorities.jwt[].createdAt string, or number, or null    
authorities.jwt[].id string    
authorities.jwt[].jwk object    
authorities.jwt[].jwk.alg string    
authorities.jwt[].jwk.crv string    
authorities.jwt[].jwk.e string    
authorities.jwt[].jwk.ek string    
authorities.jwt[].jwk.ext boolean    
authorities.jwt[].jwk.key_ops list    
authorities.jwt[].jwk.key_ops[] string    
authorities.jwt[].jwk.kid string    
authorities.jwt[].jwk.kty string    
authorities.jwt[].jwk.n string    
authorities.jwt[].jwk.pub string    
authorities.jwt[].jwk.use string    
authorities.jwt[].jwk.x string    
authorities.jwt[].jwk.x5c list    
authorities.jwt[].jwk.x5c[] string    
authorities.jwt[].jwk.x5t string    
authorities.jwt[].jwk.x5t#S256 string    
authorities.jwt[].jwk.x5u string    
authorities.jwt[].jwk.y string    
authorities.jwt[].keyType string    
authorities.maxRetained number    
authorities.realm string    
authorities.root object    
authorities.root.certificatePem string, or null    
authorities.root.notAfter string, or null    
authorities.root.subject string, or null    
authorities.source string    
authorities.trustAnchors list    
authorities.trustAnchors[].certificatePem string    
authorities.trustAnchors[].id string    
authorities.trustAnchors[].notAfter string    
authorities.trustAnchors[].notBefore string    
authorities.trustAnchors[].source string    
authorities.trustAnchors[].subject string    
authorities.x509 list    
authorities.x509[].active boolean    
authorities.x509[].certificatePem string    
authorities.x509[].createdAt string, or number, or null    
authorities.x509[].id string    
authorities.x509[].keyType string    
authorities.x509[].notAfter string    
authorities.x509[].notBefore string    
authorities.x509[].serialHex string    
authorities.x509[].source string    
authorities.x509[].subject string    
authorityState object    
authorityState.federated list    
authorityState.federated[].bundleEndpointProfile string, or null    
authorityState.federated[].bundleEndpointUrl string, or null    
authorityState.federated[].createdAt string, or number, or null    
authorityState.federated[].endpointSpiffeId string, or null    
authorityState.federated[].jwtKeys integer    
authorityState.federated[].keys integer    
authorityState.federated[].refreshHint number    
authorityState.federated[].sequence number    
authorityState.federated[].trustDomain string    
authorityState.federated[].trustDomainId string    
authorityState.federated[].updatedAt string, or number, or null    
authorityState.federated[].x509Keys integer    
authorityState.jwtAuthorities list    
authorityState.jwtAuthorities[].active boolean    
authorityState.jwtAuthorities[].alg string, or null    
authorityState.jwtAuthorities[].createdAt string, or number, or null    
authorityState.jwtAuthorities[].id string    
authorityState.jwtAuthorities[].notAfter string, or null    
authorityState.x509Authorities list    
authorityState.x509Authorities[].active boolean    
authorityState.x509Authorities[].createdAt string, or number, or null    
authorityState.x509Authorities[].id string    
authorityState.x509Authorities[].keyType string    
authorityState.x509Authorities[].notAfter string    
authorityState.x509Authorities[].subject string    
bundle object    
bundle.path string    
bundle.refreshHint number    
bundle.sequence number    
counts object    
counts.agents integer    
counts.entries integer    
counts.maxAgents number    
counts.maxEntries number    
counts.maxFederatedBundles number    
enabled boolean    
error string    
federated list    
federated[].bundleEndpointProfile string, or null    
federated[].bundleEndpointUrl string, or null    
federated[].createdAt string, or number, or null    
federated[].endpointSpiffeId string, or null    
federated[].jwtKeys integer    
federated[].keys integer    
federated[].refreshHint number    
federated[].sequence number    
federated[].trustDomain string    
federated[].trustDomainId string    
federated[].updatedAt string, or number, or null    
federated[].x509Keys integer    
keyTypes list    
keyTypes[].id string    
keyTypes[].jwtAlg string, or null    
keyTypes[].kind string    
keyTypes[].label string    
keyTypes[].what string    
listeners object    
listeners.brokerApi list    
listeners.brokerApi[].address string    
listeners.brokerApi[].attested boolean    
listeners.brokerApi[].authentication string    
listeners.brokerApi[].error string    
listeners.brokerApi[].listening boolean    
listeners.brokerApi[].peerCredentials boolean    
listeners.brokerApi[].port integer    
listeners.brokerApi[].realm string    
listeners.brokerApi[].restricted boolean    
listeners.brokerApi[].socket boolean    
listeners.brokerApi[].tls boolean    
listeners.serverApi list    
listeners.serverApi[].address string    
listeners.serverApi[].attested boolean    
listeners.serverApi[].authentication string    
listeners.serverApi[].error string    
listeners.serverApi[].listening boolean    
listeners.serverApi[].peerCredentials boolean    
listeners.serverApi[].port integer    
listeners.serverApi[].realm string    
listeners.serverApi[].restricted boolean    
listeners.serverApi[].socket boolean    
listeners.serverApi[].tls boolean    
listeners.workloadApi list    
listeners.workloadApi[].address string    
listeners.workloadApi[].attested boolean    
listeners.workloadApi[].authentication string    
listeners.workloadApi[].error string    
listeners.workloadApi[].listening boolean    
listeners.workloadApi[].peerCredentials boolean    
listeners.workloadApi[].port integer    
listeners.workloadApi[].realm string    
listeners.workloadApi[].restricted boolean    
listeners.workloadApi[].socket boolean    
listeners.workloadApi[].tls boolean    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
ready boolean    
serverApiAuthenticated boolean    
serverId string    
settings list    
settings[].key string    
settings[].value string, or null    
settingsForms object    
settingsForms.context object    
settingsForms.context.configFile string, or null    
settingsForms.context.defaultsFile string, or null    
settingsForms.context.inRealm boolean    
settingsForms.context.persistenceMode string    
settingsForms.context.persistsAppconfig boolean    
settingsForms.context.persistsRealms boolean    
settingsForms.context.realmId string    
settingsForms.editableCount integer    
settingsForms.groups list    
settingsForms.groups[].group string    
settingsForms.groups[].settings list    
settingsForms.groups[].settings[].appconfigPath string    
settingsForms.groups[].settings[].csvValueNotes map    
settingsForms.groups[].settings[].csvValueNotes.{key} string    
settingsForms.groups[].settings[].csvValues list    
settingsForms.groups[].settings[].csvValues[] string, or number, or boolean, or null    
settingsForms.groups[].settings[].default list, or string, or number, or boolean, or null    
settingsForms.groups[].settings[].default[] object   Nested deeper than this page draws.
settingsForms.groups[].settings[].description string    
settingsForms.groups[].settings[].editRefusal string    
settingsForms.groups[].settings[].editable boolean    
settingsForms.groups[].settings[].enumValues list    
settingsForms.groups[].settings[].enumValues[] string, or number, or boolean, or null    
settingsForms.groups[].settings[].env list, or string    
settingsForms.groups[].settings[].env[] object   Nested deeper than this page draws.
settingsForms.groups[].settings[].group string    
settingsForms.groups[].settings[].key string    
settingsForms.groups[].settings[].label string    
settingsForms.groups[].settings[].legacyEnv list, or string    
settingsForms.groups[].settings[].legacyEnv[] object   Nested deeper than this page draws.
settingsForms.groups[].settings[].masked boolean    
settingsForms.groups[].settings[].max number    
settingsForms.groups[].settings[].min number    
settingsForms.groups[].settings[].ordered boolean    
settingsForms.groups[].settings[].overridden boolean    
settingsForms.groups[].settings[].realmSettable boolean    
settingsForms.groups[].settings[].restartReason string    
settingsForms.groups[].settings[].selectAll object    
settingsForms.groups[].settings[].selectAll.aloneWhileOn list    
settingsForms.groups[].settings[].selectAll.aloneWhileOn[] object   Nested deeper than this page draws.
settingsForms.groups[].settings[].selectAll.onlyWhileOn list    
settingsForms.groups[].settings[].selectAll.onlyWhileOn[] object   Nested deeper than this page draws.
settingsForms.groups[].settings[].source string    
settingsForms.groups[].settings[].step number    
settingsForms.groups[].settings[].text string, or null    
settingsForms.groups[].settings[].type string    
settingsForms.groups[].settings[].value list, or string, or number, or boolean, or null    
settingsForms.groups[].settings[].value[] object   Nested deeper than this page draws.
settingsForms.overridden list    
settingsForms.overridden[] string    
settingsForms.page string    
settingsForms.setWith string    
settingsForms.settingCount integer    
settingsForms.sharedWith map    
settingsForms.sharedWith.{key} list    
settingsForms.sharedWith.{key}[].label string    
settingsForms.sharedWith.{key}[].path string    
trustDomain string    
trustDomainId string    
workloadAttestation object    
workloadAttestation.attestors list    
workloadAttestation.attestors[].enabled boolean    
workloadAttestation.attestors[].type string    
workloadAttestation.attestors[].verifies string    
workloadAttestation.connections list    
workloadAttestation.connections[].error string, or null    
workloadAttestation.connections[].gid number    
workloadAttestation.connections[].note string, or null    
workloadAttestation.connections[].pid number    
workloadAttestation.connections[].pidfdSource string    
workloadAttestation.connections[].selectors integer    
workloadAttestation.connections[].tag string    
workloadAttestation.connections[].uid number    
workloadAttestation.connections[].visible boolean    
workloadAttestation.nativeModule boolean    
workloadAttestation.problem string, or null    
workloadAttestation.tcp object    
workloadAttestation.tcp.attested boolean    
workloadAttestation.tcp.declared boolean    
workloadAttestation.tcp.host string    
workloadAttestation.tcp.listening boolean    
workloadAttestation.tcp.port integer    
workloadAttestation.tcp.served boolean    
workloadAttestation.tcp.state string    
workloadAttestation.tcp.why string    
workloadAttestation.unattestedSocketServed boolean    
workloadAttestation.unknownConfigured list    
workloadAttestation.unknownConfigured[] string    

GET /admin-api/spiffe/agents

getSpiffeAgents

The agents that have attested here, filtered and paged

An agent appears when it calls AttestAgent on the SPIRE Server API. These entries are a RECORD rather than configuration — everything on them was written by this service — which is why nothing about an agent is editable. The writes are the ban, the unban, forgetting one, and creating a join token for an agent that has not attested yet.

Node attestation is verified or refused. An agent here attested with a type the realm accepts (spiffe.nodeAttestors) and an attestor verified, and its selectors are the ones that attestor derived (#40, 2026-09-21).

Mirrors GET /admin/cert-issuance on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
agent query string   One agent, by its SPIFFE ID — always under /spire/agent/. The reply then carries its directory entry, where the cn is a DIGEST of the SPIFFE ID and spiffeAgentId is the identity.
q query string   Substring of the agent id, the attestation type or any selector, case-insensitive.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The matching agents with the paging that found them.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
agents list    
agents[].attestationType string    
agents[].attestations number    
agents[].attributes map    
agents[].attributes.{key} list    
agents[].attributes.{key}[] string    
agents[].banned boolean    
agents[].canReattest boolean    
agents[].dn string    
agents[].expiresAt number    
agents[].firstSeen string    
agents[].id string    
agents[].lastSeen string    
agents[].selectorTexts list    
agents[].selectorTexts[] string    
agents[].selectors list    
agents[].selectors[].type string    
agents[].selectors[].value string    
agents[].svidHash string    
container string    
error string    
filter object    
filter.q string    
found boolean    
id string    
matched integer    
max number    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
serverApiAuthenticated boolean    
total integer    

POST /admin-api/spiffe/agents/ban

banSpiffeAgent

Refuse this agent at AttestAgent

ONE OF THE FEW REFUSALS IN THIS SERVICE, and it earns its place: a ban that did not refuse would make the button a lie. A banned agent gets PermissionDenied from AttestAgent.

Whatever SVID it already holds keeps working until it expires. There is no revocation in SPIFFE, so a ban stops the NEXT identity rather than the current one.

The agent’s own entry under ou=users — the one every identity this trust domain issues a certificate to gets — is marked spiffeCredentialStatus: revoked, and unbanning marks it active again. It is never deleted, and nothing reads that flag back.

Mirrors POST /admin/spiffe/agents on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
agent string yes The agent’s SPIFFE ID.

200: The agent as it now stands.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/agents/delete

deleteSpiffeAgent

Forget an agent

Deleting is forgetting, not revoking. It reappears the moment it attests again, because attestation is not checked here. Ban it if the intention was to stop it.

Mirrors POST /admin/spiffe/agents on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
agent string yes The agent’s SPIFFE ID.

200: That it is forgotten.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/agents/join-token

createSpiffeJoinToken

Mint a join token for a workload agent

How an operator provisions the sidecar agent that serves the Workload API on a Unix socket next to a workload (#324). The SPIRE Server API is what the agent attests to; this is the same join-token store CreateJoinToken writes, reached here because there is no admin SVID until a Workload API exists to fetch one from.

The token is shown once, in token and in message, and is not recorded. agentSpiffeId is the identity the token will attest, which is a digest of the token and is safe to keep: parent that agent’s workload entries on it. An optional agentId registers an alias the way SPIRE does, and is not the agent field the ban takes.

Mirrors POST /admin/spiffe/agents on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body (optional)

Member Type Required What it is
agentId string   Optional alias SPIFFE ID, registered as an entry parented on the agent this token attests.
ttl number   Lifetime in seconds. Omit it to use spiffe.joinTokenTtl.

200: The token, once, and the agent SPIFFE ID it will attest.

Member Type Required What it is
agentSpiffeId string    
errors list    
errors[] string    
expiresAt string, or number, or null    
message string    
ok boolean yes  
token string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
agentSpiffeId string    
errors list    
errors[] string    
expiresAt string, or number, or null    
message string    
ok boolean yes  
token string    

POST /admin-api/spiffe/agents/unban

unbanSpiffeAgent

Let this agent attest again

Mirrors POST /admin/spiffe/agents on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
agent string yes The agent’s SPIFFE ID.

200: The agent as it now stands.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
agent object    
agent.attestationType string    
agent.attestations number    
agent.attributes map    
agent.attributes.{key} list    
agent.attributes.{key}[] string    
agent.banned boolean    
agent.canReattest boolean    
agent.dn string    
agent.expiresAt number    
agent.firstSeen string    
agent.id string    
agent.lastSeen string    
agent.selectorTexts list    
agent.selectorTexts[] string    
agent.selectors list    
agent.selectors[].type string    
agent.selectors[].value string    
agent.svidHash string    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

GET /admin-api/spiffe/brokers

getSpiffeBrokers

Who may call the SPIFFE Broker API, filtered and paged

The brokers of spiffe.brokers: each SPIFFE ID authorized to call the SPIFFE Broker API (Incubating) on this realm’s mutual-TLS Broker endpoint, and which workload references it may use — pid (WorkloadPIDReference), k8s (a KubernetesObjectReference to a pod) or *. An entry that does not parse is listed with its problem and authorizes nothing. listeners is where the endpoint is bound in this realm, and port its spiffe.brokerPort.

Mirrors GET /admin/cert-issuance on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
q query string   Substring of a broker’s SPIFFE ID or reference types, case-insensitive.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The matching brokers with the paging that found them.

Member Type Required What it is
brokers list    
brokers[].id string    
brokers[].problem string, or null    
brokers[].referenceTypes list    
brokers[].referenceTypes[] string    
filter object    
filter.q string    
listeners list    
listeners[].address string    
listeners[].attested boolean    
listeners[].authentication string    
listeners[].error string    
listeners[].listening boolean    
listeners[].peerCredentials boolean    
listeners[].port integer    
listeners[].realm string    
listeners[].restricted boolean    
listeners[].socket boolean    
listeners[].tls boolean    
matched integer    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
port string, or null    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
referenceTypes list    
referenceTypes[] string    
setting string    
total integer    
trustDomain string    

POST /admin-api/spiffe/brokers/remove

removeSpiffeBroker

Take a broker off the list

Its next call to the SPIFFE Broker API is refused PERMISSION_DENIED. SVIDs it already fetched for a workload keep working until they expire — SPIFFE has no revocation.

Mirrors POST /admin/spiffe/brokers on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
id string yes The broker’s SPIFFE ID.

200: Whether it was listed.

Member Type Required What it is
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/brokers/set

setSpiffeBroker

Authorize a broker, or replace what it may reference

Writes the broker into spiffe.brokers in the realm the call is made in; it takes effect on the broker’s next call. referenceTypes must name at least one of pid, k8s and * — SPIRE’s allowed_reference_types, and the endpoint is TCP, so each allows that type over TCP. A process id means something only on the node it was read on: allow pid only to a broker on this host. A broker from a federated trust domain is verified against that domain’s bundle.

Mirrors POST /admin/spiffe/brokers on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
id string yes The broker’s SPIFFE ID.
referenceTypes list yes What it may reference: one or more of pid, k8s and *.
referenceTypes[] one of pid, k8s, *    

200: The broker as it now stands.

Member Type Required What it is
errors list    
errors[] string    
id string    
message string    
ok boolean yes  
referenceTypes list    
referenceTypes[] string    

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
errors list    
errors[] string    
id string    
message string    
ok boolean yes  
referenceTypes list    
referenceTypes[] string    

GET /admin-api/spiffe/entries

getSpiffeEntries

The registration entries, filtered and paged

A registration entry says which SPIFFE ID a workload gets, under which parent, matching which selectors. It is the most important object in a SPIFFE deployment: the Workload API answers out of it.

The entries ARE the registry. They live under ou=entries,ou=spiffe in the embedded LDAP directory and nothing caches them, so an ldapmodify is visible here on the next call and changes what the next SVID looks like.

The selectors restrict nothing here. They are recorded, reported, and used by the SPIRE Server API’s GetAuthorizedEntries — and the Workload API hands every caller every identity, because nothing in this service attests a workload.

Mirrors GET /admin/cert-issuance on the admin console.

The reply also carries protocolEndpoints: every endpoint of this family in the realm the call arrived in, as { name, methods, url } (plus route for an HTTP endpoint, transport for a socket, and registered: false for a route the router no longer has).

Scope: admin:read.

Parameters

Name In Type Required What it is
entry query string   One entry, by its id — the 32 hex characters this registry minted, which is what the SPIRE Server API calls id. The reply then carries that entry with every attribute of its directory entry.
q query string   Substring of the SPIFFE ID, the parent, the entry id, the hint or any selector, case-insensitive.
origin query one of seed, console, api, grpc, auto, ldap, unstated   How the entry got here. auto is one this service INVENTED for a workload that matched nothing, which is the setting spiffe.autoCreateEntries — telling those from entries somebody meant is the whole reason this field exists.
page query integer   Which page of the match to return. CLAMPED rather than refused: a page past the end returns the last one, and the reply says which page it actually is.
per query integer   Rows per page. Defaults to 50 and is capped at 300. On a drill-down it is SHARED by every list in the reply, which each carry a page number of their own.
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

200: The matching registration entries with the paging that found them, or one entry with its directory entry when entry was given.

Member Type Required What it is
container string    
defaults object    
defaults.jwtSvidTtl string, or null    
defaults.x509SvidTtl string, or null    
editable list    
editable[] string    
entries list    
entries[].admin boolean    
entries[].attributes map    
entries[].attributes.{key} list    
entries[].attributes.{key}[] string    
entries[].createdAt string, or number, or null    
entries[].dn string    
entries[].dnsNames list    
entries[].dnsNames[] string    
entries[].downstream boolean    
entries[].expired boolean    
entries[].expiresAt number    
entries[].federatesWith list    
entries[].federatesWith[] string    
entries[].hint string    
entries[].id string    
entries[].jwtSvidTtl number    
entries[].lastSvidAt string    
entries[].modifiedAt string, or number, or null    
entries[].origin string    
entries[].parentId string    
entries[].revisionNumber number    
entries[].selectorTexts list    
entries[].selectorTexts[] string    
entries[].selectors list    
entries[].selectors[].type string    
entries[].selectors[].value string    
entries[].spiffeId string    
entries[].storeSvid boolean    
entries[].svidsIssued number    
entries[].x509SvidTtl number    
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
error string    
filter object    
filter.origin string    
filter.q string    
found boolean    
id string    
matched integer    
max number    
origins list    
origins[] string    
paging object    
paging.firstRow integer    
paging.lastRow integer    
paging.noun string    
paging.page integer    
paging.pages integer    
paging.param string    
paging.perPage integer    
paging.total integer    
protocolEndpoints list    
protocolEndpoints[].listening boolean    
protocolEndpoints[].methods list, or string    
protocolEndpoints[].methods[] string    
protocolEndpoints[].name string    
protocolEndpoints[].registered boolean    
protocolEndpoints[].route string    
protocolEndpoints[].transport string    
protocolEndpoints[].url string    
serverApiAuthenticated boolean    
total integer    
trustDomain string    

400: The answer.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/spiffe/entries/create

createSpiffeEntry

Register an identity

Three refusals and no others: a SPIFFE ID that is not one, a SPIFFE ID in ANOTHER trust domain (this service is the issuing authority for exactly one, and cannot sign for somebody else’s — that is what federation is for), and a SPIFFE ID under the reserved /spire path, which belongs to this server and the agents it attests.

A DUPLICATE SPIFFE ID IS ALLOWED. Two entries granting one identity under different parents is a real configuration and SPIRE permits it.

This is the same function BatchCreateEntry on the SPIRE Server API calls, writing the same directory entry an ldapadd would.

Mirrors POST /admin/spiffe/entries on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
dnsNames string   Comma-separated DNS subjectAltNames, added beside the SPIFFE ID. What makes an SVID usable by TLS software that checks a hostname and cannot read a SPIFFE ID.
federatesWith string   Comma-separated trust domain names whose bundles are handed to a holder of this identity. A name with no bundle here contributes nothing rather than failing.
hint string   Operator guidance when a workload gets more than one SVID — internal, external. Passed through verbatim; nothing here reads it.
jwtSvidTtl integer   Seconds. 0 means spiffe.jwtSvidTtl.
parentId string   The agent or server it hangs beneath. Defaults to this server’s own SPIFFE ID, which is what SPIRE uses for an entry describing a workload rather than a node.
selectors string   Comma-separated type:value pairs, split on the FIRST colon only — so docker:label:app:web is type docker and value label:app:web. An entry with NO selectors matches every workload, which is how a catch-all is written and is also the shape of one somebody forgot to finish.
spiffeId string yes The identity this entry grants.
x509SvidTtl integer   Seconds. 0 means spiffe.svidTtl.

200: The entry as it now stands, with its new id.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/entries/delete

deleteSpiffeEntry

Remove an entry

Anything holding an SVID minted from it keeps that SVID until it expires. SPIFFE has no revocation — the answer is a short lifetime and rotation, which is why the default X509-SVID lifetime here is an hour and the JWT-SVID one is five minutes.

If this was the LAST entry naming that SPIFFE ID, the identity’s directory entry under ou=users is marked spiffeCredentialStatus: revoked with the reason on it. The entry is NOT deleted, and that flag is not a certificate status: nothing reads it back and no SVID is refused because of it. Deleting one of several entries that name the same identity changes nothing there.

A seeded entry stays deleted until a restart: nothing here is persisted, but nothing re-creates it either, because an operator who deleted it meant to.

Mirrors POST /admin/spiffe/entries on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
entry string yes The entry id.

200: That it is gone.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/entries/update

updateSpiffeEntry

Change one field of an entry

What may be changed is DECLARED and not DERIVED. The declared half is what the entry may DO — the SPIFFE ID, the parent, the selectors, the DNS names, the lifetimes, the hint, the flags — and it is what the Workload API reads. The derived half is what HAPPENED: the revision number, the SVID counter, when it was created. Those are refused with a list of what is not, because a call that could rewrite them would make this registry lie about the service’s own behaviour in a way indistinguishable from the recording being broken.

ldapmodify still reaches everything, which is deliberate: refusing it HERE is the difference between offering an operation and merely not preventing it.

The change applies to the NEXT SVID issued from this entry. Nothing already issued changes, and there is nothing to invalidate — SPIFFE has no revocation.

Mirrors POST /admin/spiffe/entries on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
entry string yes The entry id.
field one of spiffeId, parentId, selectors, dnsNames, federatesWith, x509SvidTtl, jwtSvidTtl, hint, expiresAt, admin, downstream, storeSvid yes Which field. Anything else is refused naming these.
value string   A list field takes comma-separated values and an empty value CLEARS it; a boolean takes true or false; a TTL takes seconds.

200: The entry as it now stands, at its new revision.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
entry object    
entry.admin boolean    
entry.attributes map    
entry.attributes.{key} list    
entry.attributes.{key}[] string    
entry.createdAt string, or number, or null    
entry.dn string    
entry.dnsNames list    
entry.dnsNames[] string    
entry.downstream boolean    
entry.expired boolean    
entry.expiresAt number    
entry.federatesWith list    
entry.federatesWith[] string    
entry.hint string    
entry.id string    
entry.jwtSvidTtl number    
entry.lastSvidAt string    
entry.modifiedAt string, or number, or null    
entry.origin string    
entry.parentId string    
entry.revisionNumber number    
entry.selectorTexts list    
entry.selectorTexts[] string    
entry.selectors list    
entry.selectors[].type string    
entry.selectors[].value string    
entry.spiffeId string    
entry.storeSvid boolean    
entry.svidsIssued number    
entry.x509SvidTtl number    
errors list    
errors[] string    
id string    
message string    
ok boolean yes  

POST /admin-api/spiffe/federation-remove

removeSpiffeFederatedBundle

Forget a foreign trust domain’s bundle

Any registration entry that federates with it keeps the name and simply contributes no bundle to its workloads, which is the same state as a relationship configured before its bundle has arrived. The entries are left alone deliberately; the SPIRE Server API’s BatchDeleteFederatedBundle is where the three modes RESTRICT, DELETE and DISSOCIATE live.

Mirrors POST /admin/spiffe on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
trustDomain string yes The trust domain name.

200: That it is gone.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/spiffe/federation-set

setSpiffeFederatedBundle

Add or replace a foreign trust domain’s bundle

The bundle is PUSHED here and never PULLED by this service. The SPIFFE federation specification puts a bundle endpoint URL in the relationship and a real implementation polls it; this one records the URL and refuses to follow it — the SPIRE Server API’s RefreshBundle says so in terms — because fetching a URL somebody registered, in order to obtain a key that will then verify credentials, is a server-side request forgery with a citation attached. The same refusal this service gives WS-Federation’s wreqptr and a client’s jwks_uri.

A trust domain this service itself serves is REFUSED — any realm’s, whether or not SPIFFE is on in it (2026-09-12). The bundles are held per realm, and a federated entry naming a served domain would let an authority somebody registered in one realm authenticate workloads as another realm’s.

The document is CHECKED, which is unusual for this service: every JWK needs a use of x509-svid, jwt-svid or wit-svid, because a consumer MUST IGNORE one without it — so a bundle of keys missing that member is stored happily and then verifies nothing, with no error anywhere pointing back here.

Mirrors POST /admin/spiffe on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body

Member Type Required What it is
bundleEndpointProfile one of https_web, https_spiffe   Which profile the partner expects. Recorded.
bundleEndpointUrl string   Recorded and never fetched. It is reported back so an operator can see what the relationship says.
document object yes The bundle, as a JWK Set with spiffe_sequence and spiffe_refresh_hint. A JSON string is accepted too, which is what the console’s textarea sends.
endpointSpiffeId string   For https_spiffe, the SPIFFE ID the partner’s endpoint presents. Recorded.
trustDomain string yes The trust domain NAME — other.example, not spiffe://other.example. This service’s own is refused: a trust domain does not federate with itself, and accepting it would give it two bundles that could disagree.

200: Whether it was added or replaced.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

POST /admin-api/spiffe/rotate

rotateSpiffeAuthority

Rotate the X.509 authority, the JWT authority, or both

ROTATION IS TWO DIFFERENT ACTS. Under the service Root, which is the usual case, it re-issues the SPIFFE Issuing CA and leaves the anchor alone: the X.509 bundle does not change, and SVIDs already in the field go on verifying because their chain still reaches the same Root.

On the self-signed fallback, and for the JWT authority, a new authority is PREPENDED — everything is signed with it from that moment — and the old one stays in the published bundle, whose spiffe_sequence changes. Past spiffe.retainedAuthorities the oldest is dropped, and anything it signed stops verifying at that moment.

This is also the ONLY way to add an authority to this trust domain. The SPIRE Server API’s AppendBundle and PublishJWTAuthority are refused, because they would publish a signing key nothing here holds.

Mirrors POST /admin/spiffe on the admin console.

Scope: admin:write.

Parameters

Name In Type Required What it is
DPoP header string   RFC 9449: the proof of possession for a DPoP-bound access token, as Authorization: DPoP <token> requires.
cell query string   The cell to answer this request, where this service runs as several. Ignored in a service that runs as one.

Request body (optional)

Member Type Required What it is
which one of x509, jwt, both   Which authority. Defaults to x509.

200: What was rotated, and the new bundle sequence.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes  

400: The operation was refused; errors says why and nothing changed.

Member Type Required What it is
errors list    
errors[] string    
message string    
ok boolean yes