GET /api/v1/ready

Readiness -- is this Gateway's client build admitted by the key server?

Answers 200 when the key server admits this Gateway's release, and 503 when it does not. Every key-server connection the Gateway opens attests the signed release it runs right after it authenticates; a refusal takes the whole process out of readiness, and while it is out every route but this one and GET /api/v1/health answers 503 BUILD_NOT_ADMITTED.

It asks the key server nothing. It reports the admission state the Gateway's own connections establish, held in memory, so polling it costs the key server nothing. The Gateway re-attempts admission on a timer (TE_ATTEST_RETRY_SECONDS, default 30) and turns ready without a restart once the key server admits it -- route a load balancer on this, restart on GET /api/v1/health.

Open for the reason GET /api/v1/health is: the caller is a load balancer or an operator and holds no credential. When ready it discloses nothing but that; when not ready it names the cause, which describes this Gateway's own release and installation.

lifecycle appears only when there is something to say about the registered services' credential lifecycle (see "The registered service's credential lifecycle"): serviceRegistry when the last re-read of the service registry was refused (the registry in force, loaded at inForceSince, is still serving), and revocationSweep when the revocation sweep is failing. Neither changes the status code: the admission gate alone decides 200 or 503.

Authentication

No session required. This operation is reachable without an Authorization header. See Authenticating.

Request

No request body.

Responses

200

This Gateway's release is admitted; it is serving.

Field	Type	Required	Description
status	"ready" (constant)	yes
lifecycle	LifecycleNotice	no	Present on GET /api/v1/ready only when the credential lifecycle has something to report. It never changes the readiness status code.

LifecycleNotice

Field	Type	Required	Description
serviceRegistry	object	no	The last re-read of the service registry file was refused WHOLE; the registry in force still serves.
revocationSweep	object	no	The revocation sweep (LOOKUP_REVOCATION through the Gateway's own identity) is failing.

Example

{
  "status": "ready",
  "lifecycle": {
    "serviceRegistry": {
      "status": "reload-refused",
      "refusedAt": "...",
      "inForceSince": "...",
      "detail": "..."
    },
    "revocationSweep": {
      "status": "failing",
      "since": "...",
      "lastSucceededAt": "...",
      "detail": "..."
    }
  }
}

503

BUILD_NOT_ADMITTED (scope: process, retryable: true, Retry-After) -- the key server does not admit this Gateway's release, and detail names why: the key server's own refusal, a release manifest that is not configured while the key server enforces a code-signing level, or an installed file that no longer matches the signed manifest (the file is named). Or CAPACITY_UNAVAILABLE (scope: process, Retry-After) -- this Gateway is at its request ceiling (see "Rate and capacity limits").

413

PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.

Error handling

Every failure answers JSON carrying at least code and detail. Match on code — detail is written for a human debugging the call and its wording is not part of the contract. See the error model.

Status	Meaning
503	BUILD_NOT_ADMITTED (scope: process, retryable: true, Retry-After) -- the key server does not admit this Gateway's release, and detail names why: the key server's own refusal, a release manifest that is not configured while the key server enforces a code-signing level, or an installed file that no longer matches the signed manifest (the file is named). Or CAPACITY_UNAVAILABLE (scope: process, Retry-After) -- this Gateway is at its request ceiling (see "Rate and capacity limits").
413	PAYLOAD_TOO_LARGE (retryable: false) -- the request body is larger than this deployment accepts. It was refused before it was parsed, and the connection is closed. Nothing was sent to the key server.