Auth & responses

Base URL: https://<first-master-ip>:31007 (see k7 api status / k7 api endpoint).

Transport#

The NodePort is served over HTTPS by default. On the default install the certificate is signed by a playbook-minted cluster CA at /etc/k7/tls/ca.crt on the node — copy it to your client and trust it (curl --cacert ca.crt …, Client(..., verify_ssl="ca.crt"), k7 config set api.ca ca.crt). Clusters installed with --api-hostname present a Let’s Encrypt certificate; --api-tls-cert/--api-tls-key an operator-supplied one; --api-insecure-http serves plain http://. Disabling verification on an https:// URL is rejected by the CLI and SDK. See Security model.

Authentication#

Two kinds of credential are accepted:

X-API-Key: k7_<id>_<secret># orAuthorization: Bearer k7_<id>_<secret># or, on a cluster installed with --oidc-*:Authorization: Bearer <OIDC JWT>

Tokens starting k7_ (and the X-API-Key header) always take the API-key path; anything else on Authorization: Bearer is validated as an OIDC JWT against the configured issuer (RS256/ES256, iss, aud, exp, sub required). A bad key is never retried as OIDC.

Every principal resolves to a role: read-only or user inside one tenant, or operator / admin cluster-wide. API keys carry their role (k7 generate-api-key --role …); OIDC subjects get theirs from the role bindings (PUT /api/v1/role-bindings). One PERMISSIONS table maps every route to the roles that may call it. Checks compose — route role, then tenant, then the key’s namespace / node narrowing — and the first failure is a 403 naming the missing role or scope. See Tenants, roles and OIDC.

All endpoints return standard HTTP codes. 401 Unauthorized if the credential is missing, invalid or expired. 403 Forbidden if the role does not cover the route (a read-only key calling exec, a user key reading GET /api/v1/nodes/storage), if a tenant key touches another tenant’s namespace or an all-namespaces operation, or if a create exceeds a tenant quota (QuotaExceeded). In production mode, keys without a tenant or cluster role (pre-0.5 unscoped_legacy keys) get 403 on every route until re-issued.

Every response carries X-Request-ID (echoed in the audit log) and X-K7-Mode (production or development).

Response envelope#

Successful responses:

{ "data": ... }

Errors:

{ "error": { "code": "BadRequest", "message": "..." } }

Common error codes:

• BadRequest (400): Invalid input or missing parameters
• Unauthorized (401): Missing or invalid API key
• Forbidden (403): role, tenant or namespace/node scope does not cover the request
• QuotaExceeded (403): tenant quota hit — message names the dimension, limit, usage and request
• LimitNotEnforceable (400): a configured tenant limit (diskIO, network on k7d / k7d-fc, disk quota on k7d / k7d-fc) cannot be enforced by the backend, so the create is refused rather than running unlimited
• NotFound (404): Resource was not found
• Conflict (409): Resource already exists
• UnprocessableEntity (422): Validation failed
• TenantConflict (500): a namespace is claimed by two Tenant objects (only possible by hand-written CRs)
• InternalServerError (500): Unhandled error
• PrometheusUnavailable (502): /usage could not query Prometheus
• 503 Service Unavailable: the API refuses rather than guesses — key-store snapshot older than 60 s, OIDC JWKS refresh failed, quota Lease not acquired within 5 s (QuotaLockTimeout / QuotaLockLost), a transient create failure such as the registry allowlist’s DNS not resolving, or a usage spool above its high-water mark with --metering-require-delivery (UsageSpoolFull)

Headers#

Required headers for requests with body:

Content-Type: application/json

Authentication headers (either):

X-API-Key: <your-key># orAuthorization: Bearer <your-key>

Resources#

• Sandboxes: create, list, get, delete, delete-all, pause, resume, fork
• Exec: run a command in a sandbox and get stdout/stderr/exit_code
• Metrics: CPU and memory usage per sandbox
• Snapshots: list, inspect, create, delete, restore, GC
• Identity: who am I, OIDC discovery, API keys, role bindings
• Tenants: namespaces, quotas, defaults, dedicated nodes; usage showback
• Nodes: storage pools, dedication; remote install (opt-in)

Endpoints at a glance#