# API guide

The base URL is the configured `advertise_url`; all timestamps are UTC RFC 3339.

`GET /healthz` is unauthenticated process liveness. `GET /readyz` returns 200 only when the node can serve its configured role; it returns 503 otherwise. All `/v1` operations authenticate according to `none`, HTTP bearer, or HTTPS mTLS. Bearer access is restricted to lease paths; detailed reports require an operator identity.

Each authenticated principal is authorized for exactly one `license_type`, either `phocol` or `lmc_exporter`. Acquire requests for another type return `forbidden_license_type`; lease reads, renewals, and releases also require the owning principal and its allowed type. This authorization does not filter customer-wide metadata: authenticated `none` and mTLS requests to `/v1/license` and `/v1/entitlements` return every type declared in the Gateway license. Bearer callers cannot access those non-lease endpoints. See [client authentication](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/security/deployment-security/#configure-client-authentication) to configure multiple principals.

<table><caption class="sr-only">API guide</caption><thead><tr><th scope="col">Group</th><th scope="col">Operations</th></tr></thead><tbody><tr><td>Status</td><td><code>GET /v1/status</code>, <code>/v1/license</code>, <code>/v1/entitlements</code>, <code>/v1/ha</code></td></tr><tr><td>Leases</td><td><code>POST /v1/leases</code>, <code>GET</code>/<code>DELETE /v1/leases/{lease_id}</code>, <code>POST /v1/leases/{lease_id}/renew</code></td></tr><tr><td>Support</td><td>`GET /v1/report?include_leases=true</td></tr></tbody></table>

Acquire and renew require `Idempotency-Key`; retry ambiguity with the same key. Every response carries `X-Correlation-Id`. Errors are JSON with a stable `code`: retry `not_active`, `store_unavailable`, and `rate_limited` (honour `Retry-After`); investigate `capacity_exhausted`, `license_invalid`, and `lease_conflict`. TLS and authentication setup are in [security](https://portal.cjcit.io/knowledge-base/keystone_gateway/0.2/security/deployment-security/).