Docs API reference

Resolution

Signed workload trust assertions and the keys that verify them.

2 operations. See the API overview for authentication, errors, idempotency and caching rules that apply to all of them.

Resolve a trust domain

GET/v1/resolve

Authentication: Public, no credentials
Operation ID: resolveTrustDomain

Returns a signed assertion naming the organization that authorized the trust domain, or an explicit inactive status. Never cached: every response, errors included, is no-store. An assertion may only be retained until its own exp (at most 300 seconds after it was read); resolve again rather than caching.

200 with status: active carries assertion, a compact JWS. Verify it against /.well-known/jwks.json (see ResolutionAssertionPayload for the header and claims).
200 with any other status carries assertion: null and a reason. status is the binding status (suspended, expired, withdrawn) or inactive when a resolution rule failed. These are normal answers, not errors.
404 means no issuer binding has ever been published for that exact trust domain.
503 unavailable means no assertion could be issued right now. One case is "Signing is paused for recovery.": while the directory recovers its database, it signs nothing until every withdrawal recorded since the backup has been re-applied. Non-active answers are still served. Retry later, and keep treating the trust domain as unverified until then.

Exactly one trust_domain is required, and it must be exact: lowercase, [a-z0-9._-], at most 255 characters, no empty labels and not an IP address. There is no wildcard or parent-domain matching.

Parameters

Name	In	Required	Type	Description
`trust_domain`	query	Yes	string	The exact SPIFFE trust domain (no `spiffe://`). at most 255 characters; pattern `^[a-z0-9._-]+$` example `agents.payments.example.com`

Responses

Status	Description	Body
200	A resolution result (active with an assertion, or inactive with a reason). Headers: `Cache-Control`: `no-store`	`application/json` `ResolveResponse`
400	`invalid_request`. Malformed JSON, an invalid or unknown field (see `field_errors`), a missing or malformed `Idempotency-Key`, or a bad query. Also used with status `413` (body over 64 KiB) and `415` (wrong `Content-Type`).	`application/json` `Error`
404	`not_found`. No such resource, or one the caller may not see (the two are indistinguishable by design).	`application/json` `Error`
503	`unavailable` (temporarily unavailable; also a feature that is not configured in this deployment) or `provider_unavailable` (an identity provider is not configured). Both are 503. During maintenance (for example a database recovery) every mutating request answers `unavailable` "The directory is under maintenance; try again later." Reads keep working.	`application/json` `Error`

200 Active binding

json

{
  "trust_domain": "agents.payments.example.com",
  "status": "active",
  "assertion": "eyJhbGciOiJFUzI1NiIsInR5cCI6ImFydC1yZXNvbHV0aW9uK2p3dDt2PTEiLCJraWQiOiJaazNwMHlROG1XY1YxblQ1ckU3dUoyaEw5c0E0ZEY2Z0I4eE4wb0tpSDN3In0.eyJpc3MiOiJodHRwczovL3N2aWQuaW8iLCJhdWQiOiJ3b3JrbG9hZC1kaXJlY3RvcnktcmVzb2x2ZXItdjEiLCJpYXQiOjE3OTEyMDE2MDAsIm5iZiI6MTc5MTIwMTYwMCwiZXhwIjoxNzkxMjAxOTAwLCJzY2hlbWFfdmVyc2lvbiI6MSwiYmluZGluZ19pZCI6ImJuZF85cjJ0NXc4ejFiNGQ3ZjBoM2s2bjlxMnM1diIsImJpbmRpbmdfdmVyc2lvbiI6MSwic3RhdHVzIjoiYWN0aXZlIiwib3JnYW5pemF0aW9uX2lkIjoib3JnXzdrM205cTJ4OGQ1ZjFoNGo2bjBwMnI0dDh2Iiwib3JnYW5pemF0aW9uX25hbWUiOiJFeGFtcGxlIFBheW1lbnRzLCBJbmMuIiwidmVyaWZpZWRfZG9tYWluIjoicGF5bWVudHMuZXhhbXBsZS5jb20iLCJ0cnVzdF9kb21haW4iOiJhZ2VudHMucGF5bWVudHMuZXhhbXBsZS5jb20iLCJwcm9maWxlIjoic3BpZmZlLXg1MDkiLCJ3b3JrbG9hZF9zY29wZSI6WyIvYWdlbnQvY2hlY2tvdXQiLCIvYWdlbnQvcmVmdW5kcyJdLCJidW5kbGVfdXJsIjoiaHR0cHM6Ly9zdmlkLmlvL3YxL2lzc3Vlci1iaW5kaW5ncy9ibmRfOXIydDV3OHoxYjRkN2YwaDNrNm45cTJzNXYvdmVyc2lvbnMvMS9idW5kbGUiLCJidW5kbGVfc2hhMjU2IjoicTdZZDNuWGswYVYycEx3OXNUNHVIYzhCekUxbVI2Zko1Z04wb0l4SzJ0QSIsImV2aWRlbmNlX3N1bW1hcnkiOnsiZG9tYWluX2NvbnRyb2wiOiJ2ZXJpZmllZCIsIm9yZ2FuaXphdGlvbl9pZGVudGl0eSI6InJldmlld2VkIiwicmVwcmVzZW50YXRpdmVfYXV0aG9yaXR5IjoidmVyaWZpZWQifSwicG9saWN5X3ZlcnNpb24iOiJkaXJlY3RvcnktcG9saWN5LXYxIn0.3BLY1a8onXcoLV1TdzP48vbxAL-AKWwDZKNqxM_EDNORYXA3RnTbu2QDTdgzrSsSdp03xAJ_ftwiF1yQtIELtA",
  "expires_at": "2026-10-05T12:05:00.000Z",
  "checked_at": "2026-10-05T12:00:00.000Z"
}

200 Suspended binding

json

{
  "trust_domain": "agents.payments.example.com",
  "status": "suspended",
  "reason": "binding_suspended",
  "assertion": null,
  "checked_at": "2026-10-05T12:00:00.000Z"
}

200 A resolution rule failed

json

{
  "trust_domain": "agents.payments.example.com",
  "status": "inactive",
  "reason": "evidence_expired",
  "assertion": null,
  "checked_at": "2026-10-05T12:00:00.000Z"
}

400 example

json

{
  "code": "invalid_request",
  "message": "Invalid organization.",
  "request_id": "req_3m6p9s2v5y8b1e4h7k0n3q6t9w",
  "field_errors": [
    {
      "field": "legal_name",
      "message": "must be 1-200 characters"
    }
  ]
}

404 example

json

{
  "code": "not_found",
  "message": "No such resource.",
  "request_id": "req_3m6p9s2v5y8b1e4h7k0n3q6t9w"
}

503 example

json

{
  "code": "unavailable",
  "message": "Temporarily unavailable.",
  "request_id": "req_3m6p9s2v5y8b1e4h7k0n3q6t9w"
}

Assertion signing keys

GET/.well-known/jwks.json

Authentication: Public, no credentials
Operation ID: getJwks

The public keys that verify resolution assertions (ES256, P-256). Includes the active signing key and any rotated verify-only keys. Only public members are published. Match the assertion's JWS kid header against keys[].kid.

Responses

Status	Description	Body
200	The JSON Web Key Set. Headers: `Cache-Control`: `public, max-age=300`	`application/json` `Jwks`
404	`not_found`. No such resource, or one the caller may not see (the two are indistinguishable by design).	`application/json` `Error`
503	`unavailable` (temporarily unavailable; also a feature that is not configured in this deployment) or `provider_unavailable` (an identity provider is not configured). Both are 503. During maintenance (for example a database recovery) every mutating request answers `unavailable` "The directory is under maintenance; try again later." Reads keep working.	`application/json` `Error`

200 example

json

{
  "keys": [
    {
      "kty": "EC",
      "crv": "P-256",
      "x": "f83OJ3D2xF1Bg8vub9tLe1gHMzV76e8Tus9uPHvRVEU",
      "y": "x_FEzRu9m36HLN_tue659LNpXW6pCyStikYjKIWI5a0",
      "kid": "Zk3p0yQ8mWcV1nT5rE7uJ2hL9sA4dF6gB8xN0oKiH3w",
      "use": "sig",
      "alg": "ES256"
    }
  ]
}

404 example

json

{
  "code": "not_found",
  "message": "No such resource.",
  "request_id": "req_3m6p9s2v5y8b1e4h7k0n3q6t9w"
}

503 example

json

{
  "code": "unavailable",
  "message": "Temporarily unavailable.",
  "request_id": "req_3m6p9s2v5y8b1e4h7k0n3q6t9w"
}

Resolve a trust domain#

Parameters

Responses

Assertion signing keys#

Responses

Resolve a trust domain

Assertion signing keys