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 |