Skip to main content

These routes manage who can call the API. Keys and role bindings need the cluster-wide admin role; whoami works for every principal; /auth/oidc is public. Concepts: Tenants, roles and OIDC.

Who am I#

Endpoint: GET /api/v1/auth/whoami

type is key or oidc; subject is the key id or the OIDC sub. grants lists the cluster role and/or one <role> on tenant <name> per tenant (an unscoped development-mode key shows user on namespaces …). For OIDC principals, issuer and groups echo the token so you can debug claim shapes.

OIDC discovery#

Endpoint: GET /api/v1/auth/oidc (no authentication)

What k7 login needs to start a device or PKCE flow: issuer, client_id, audience. 404 when the cluster was installed without the --oidc-* flags.

API keys#

Keys are stored as sha256(secret) in the kube-system/k7-api-keys Secret; every replica sees a change within 5 s. These routes are the --api path of k7 generate-api-key / list-api-keys / revoke-api-key.

Mint a key#

Endpoint: POST /api/v1/keys — admin

namestringrequired#
Human label; several keys may share it (revoke acts on all of them)
rolestringrequired#
read-only | user (per tenant) | operator | admin (cluster-wide)
tenantstring#
Required for read-only/user in production mode; forbidden for operator/admin. Must exist
expires_daysintegerrequired#
Positive integer
namespacesstring[]#
Narrow the key inside its tenant
nodesstring[]#
Kubernetes node names the key may place sandboxes on (k7 nodes list)

The token is returned once. A role/tenant mismatch or an unknown tenant is 400.

List and revoke#

  • GET /api/v1/keys — admin. Every key without its hash, plus last_used.
  • DELETE /api/v1/keys/{name} — admin. Revokes every key with that name; 404 if none. Returns {"revoked": [ids]}.

Role bindings#

Map OIDC groups, usernames or subjects to roles. Stored in ConfigMap k7-role-bindings, read on every request.

Endpoints: GET /api/v1/role-bindings, PUT /api/v1/role-bindings — admin

Each binding has exactly one matcher (group, user or subject) plus role and, for tenant roles, tenant. Several matching bindings combine as the highest role per tenant plus the highest cluster role. deny_subjects (OIDC sub or username) is the immediate stop for an account: it applies on the next request on every replica, whereas a JWT otherwise stays valid until it expires.

PUT replaces the whole document and is 400 on an unknown tenant, a role/tenant mismatch, a duplicate matcher, or a write that would leave no admin binding while no unexpired admin key exists (lock-out guard). CLI: k7 role-bindings get / apply -f.