Server discovery

Generated from capsule-server/openapi.json, the OpenAPI 3.2 document capsule-server emits and mise run openapi-check-kynos keeps current. To change a description on this page, change the annotation on the handler or model it comes from and regenerate — this file is build output. The auth model, error contract, and conventions common to every endpoint are on the REST API overview.

GET /.well-known/capsule/attestation-keys

Serve this server’s storage-attestation keys and their append-only history.

Cacheable and unauthenticated. It changes only when a key rotates, and a client that pinned a stale copy still resolves every receipt signed before it fetched — which is the property the append-only ordering buys.

Authentication: none.

Status	Body	Description
200	AttestationKeysResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

GET /.well-known/capsule/deprecation

Serve the announced deprecation cutoffs.

The same announcements server-info carries, at their own path because that is the URL the Warning: header on a below-cutoff response points a human at, and because a client polling for a cutoff should not have to refetch the whole discovery record to find one.

Authentication: none.

Status	Body	Description
200	DeprecationsResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

GET /.well-known/capsule/revoked-jti

Serve the federation capability revocation list.

Bounded by at most 24 hours of revocations, because an entry past the token’s own exp is pruned and a capability token cannot be minted to live longer than that. Public: a peer checking whether a token it holds is still good is, by construction, not yet authenticated here, and the record names no user — only opaque jtis.

Errors

Returns 503 if the revocation list cannot be read. Deliberately not an empty list: an empty list is the strongest possible claim this endpoint can make — nothing is revoked — and serving it on a storage failure would turn an outage into a silent un-revocation of every token, which is exactly what the peer-side fail-closed rule exists to prevent.

Authentication: none.

Status	Body	Description
200	RevokedJtiResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
503	CodedProblem application/problem+json	Revocation list unavailable. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

GET /.well-known/capsule/server-info

Serve this server’s public, server-scoped facts.

Unauthenticated by contract: a client deciding whether it can talk to this server at all has no credential yet, and a peer resolving the key that verifies a capability token must not need one from the server whose claims it is checking.

Authentication: none.

Status	Body	Description
200	ServerInfoResponse application/json	OK. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.
413	—	the request body exceeds the configured limit. Headers: X-Capsule-Min-Client-Build, X-Capsule-Protocol-Max, X-Capsule-Protocol-Min.

Schemas

The models these endpoints carry. A field whose type names another model links to it when this page documents that model, which it does when some path from an operation reaches it within 4 references. A model only ever reached deeper than that is named without being expanded.

AttestationKeysResponse

The .well-known/capsule/attestation-keys record.

Field	Type	Description
server_id	string	Required. This server’s canonical origin — the other half of the binding that refuses a cross-server replay.
keys	PublishedKeyResponse[]	Required. Every key this server has signed with, oldest first, the active one last.

AuthEndpointsResponse

The auth ceremony’s endpoints.

Field	Type	Description
login	string	Required. Where a session is opened.
refresh	string	Required. Where an access token is rotated.
logout	string	Required. Where a session is ended.
oidc	OidcEndpointsResponse | null	Where a sign-in through an external identity provider begins and ends, or null when this deployment has none. Always present, so a client reads one field rather than probing for one.

CodedProblem

An RFC 9457 problem detail.

Field	Type	Description
type	string	Required.
title	string	—
status	integer	Required.
detail	string	—
instance	string	—
code	string	Required. The stable error.* catalog code. The client localizes this; detail stays English. Present on every problem this server renders.

DeprecationResponse

One announced deprecation cutoff.

Field	Type	Description
min_protocol_version	string	Required. The lowest protocol_version that remains accepted after the cutoff.
announced_at	string	Required. When the announcement was first published, RFC 3339.
cutoff	string	Required. When versions below min_protocol_version stop being accepted, RFC 3339.
detail_url	string | null	Where a human reads what to do about it.

DeprecationsResponse

The .well-known/capsule/deprecation record.

Field	Type	Description
announcements	DeprecationResponse[]	Required. Every announced cutoff, in announcement order.

OidcEndpointsResponse

The OIDC ceremony’s endpoints (slice S-N1).

Field	Type	Description
authorize	string	Required. Where a client asks for an authorization URL.
callback	string	Required. Where a client presents the state and code the provider’s redirect carried.

ProtocolWindowResponse

The accepted protocol_version range.

Field	Type	Description
min	string	Required. The oldest version still accepted for writes.
max	string	Required. The newest version this server speaks.

PublishedKeyResponse

One published attestation key.

Field	Type	Description
key_id	string	Required. The fingerprint a receipt’s server_key_id selects on, lowercase hex.
public	string	Required. The hybrid public key, base64 (Ed25519 ‖ ML-DSA-65).
algorithm	string	Required. The signature algorithm this key is used with.
active_from	string	Required. When it began signing, RFC 3339.
active_to	string | null	When it stopped, or absent while it is the active key.

RevokedJtiResponse

The .well-known/capsule/revoked-jti record.

Field	Type	Description
generated_at	string	Required. When this snapshot was taken, RFC 3339. Part of the record rather than left to an HTTP Date, because the staleness rule a peer applies is a property of the list’s content — a verifier reasoning from a transport header would be trusting a cache to be honest about its own age.
max_staleness_seconds	integer	Required. How stale a cached copy of this list may be before it stops being usable, in seconds. Published so the rule is discoverable rather than a constant every peer implementation has to have read the same document to know.
revoked	RevokedTokenResponse[]	Required. Every revoked jti not yet past its own expiry, soonest expiry first.

RevokedTokenResponse

One revoked capability token.

Field	Type	Description
jti	string	Required. The token’s jti claim.
expires_at	string	Required. The token’s own exp, RFC 3339. After this the entry is pruned.

ServerInfoResponse

The .well-known/capsule/server-info record.

Server-scoped facts only. The registry’s rule — never a user list — is structural here: this type holds no user-shaped field, so there is nothing for a future edit to leak through.

Field	Type	Description
server_id	string	Required. This server’s canonical origin.
api_base_url	string	Required. Where the versioned API lives.
auth	AuthEndpointsResponse	Required. Where a client performs the auth ceremony.
federation_url	string | null	Where federated peers talk to this server. Absent when it does not federate.
protocol_version	ProtocolWindowResponse	Required. The protocol_version range accepted for writes today, both ends inclusive.
signing_key	string	Required. The raw Ed25519 public key this server’s tokens verify under, base64.
signing_algorithm	string	Required. The signature algorithm that key is used with.
deprecations	DeprecationResponse[]	Required. Announced deprecation cutoffs, in announcement order. Empty when none is pending.