HTTP API¶

All the HTTP routes kubelatch serves, who can call them, and what they do. The web interface uses this same API; you can call it with curl using a session cookie.

Who can call¶

/api conventions¶

• JSON bodies up to 64 KiB. Unknown fields and extra data are rejected (400); a larger body is 413.
• Every response carries Cache-Control: no-store.
• Errors are {"error": "<English text>", "code": "<code>", "params": {…}} (see Errors).
• An unknown route under /api/ is 404; a known route with another method is 405 with an Allow header.
• Modifying requests (POST, PUT, PATCH, DELETE) sent by a browser from another origin are rejected with 403. curl and other non-browser clients pass.
• Every response outside the proxy carries an X-Request-Id header with a fresh UUIDv7. A value sent by the client is ignored. The same id is in the server's access log line: see The server log.

Health¶

They only accept GET and HEAD; any other method is 405.

Proxy¶

Proxy errors are Kubernetes Status objects, so kubectl shows them well (Proxy errors). /clusters without a trailing slash responds 404.

CI and GitHub (outside /api)¶

These two routes use no session, cookies or origin protection: authentication travels in the request itself. They only accept POST (405 with Allow for anything else).

MCP and agent sign-in (outside /api)¶

No session, cookie or origin protection of /api applies here. They exist while KUBELATCH_MCP_ENABLED is true; otherwise 404. MCP server describes them in full.

Any other path under /.well-known/ or /oauth/ is a JSON 404.

Session and own account¶

GitHub login¶

Without GitHub configured, /api/auth/github/login, /api/auth/github/callback, /api/auth/github/link and /api/me/github/link respond 404.

OIDC login¶

The routes of OIDC login. Without OIDC configured, all of them but /api/oidc/status respond 404 oidc.disabled.

Onboarding¶

Domain access and join requests. /api/join has no session: its only proof of who is asking is the join cookie (__Host-kubelatch_join over https, kubelatch_join on plain http, ten minutes), which the OIDC callback leaves for a sign-in whose e-mail no account has. Both of its methods share a per-IP limit of their own, 30 a minute and apart from the login's (429 auth.too_many_attempts). The rest needs the administrator role. Without OIDC configured, /api/join answers 401 join.no_identity.

The join requests share /api/access-requests with the access requests of people who have an account. A join request exists only for an administrator: anyone else who names one gets 404 access_request.not_found, and so does an unknown or malformed id.

Users and bots¶

All require admin.

Clusters¶

All require admin, except GET /api/clusters/{id}/namespaces, which the owner of the whole cluster reads too.

Enrollment¶

The enrollment command calls these two routes. The kle_ token in the path is the only credential.

Environments¶

All require admin. An environment puts clusters under one name, says whether they are production and carries the rules for people's permissions on them; a cluster sits in one at most, set with PUT /api/clusters/{id}/placement.

The rules are max_ttl_seconds, the maximum lifetime, and default_ttl_seconds, the default expiry: each a whole number of seconds from 3600 to 31536000, or null for none (400 environment.ttl_invalid, with the rule in params.field), and the default never longer than the maximum (400 environment.default_over_max). Setting a rule to a value it doesn't hold needs Pro, 403 edition.feature; removing one, keeping them as they are and the production mark work in any edition.

Permissions¶

An administrator writes every permission. In Pro, the owners of a place grant, extend, preview and revoke the permissions of people and bots there too, within their limits: outside what they own 403 owner.out_of_scope (with params.index, and params.id where the route takes ids, in a batch), giving themselves access 403 owner.self, and what only an administrator grants or changes (cluster-admin, a native role, a permission the cluster makes privileged, a bot given access) 403 owner.admin_only. Anyone else gets 403 session.admin_only before the body is read. Their events carry "as": "owner" and owner_scope.

Permissions on a set¶

Every route needs the administrator role. A permission on a set gives an account or a group a role on every cluster of an environment or with a label, and follows the set. On each cluster it holds, it's a permission of /api/grants (source.kind set). Granting and extending need Pro (403 edition.feature, nothing written); previews, checking again and revoking work in every edition.

A set is {"kind": "environment", "key": "", "value": "staging"} or {"kind": "label", "key": "team", "value": "payments"}. In a list's filter, an environment is environment=staging and a label label=team:payments. A permission on a set is {"id", "subject_id", "login", "subject_kind", "subject_disabled", "group_id", "group_name", "selector", "role", "scope", "expires_at", "note", "ticket", "created_by", "created_by_login", "created_at", "revoked_at", "revoked_by", "active", "clusters"} (subject_id or group_id, the other null), and clusters has one entry per cluster of the set today: {"cluster_id", "environment", "row", "refusal"}, where row is {"id", "expires_at"} when the cluster holds the permission and refusal is {"code", "params", "kind", "decided_at"} when it doesn't (kind is transient or rule; When kubelatch decides again). While a cluster waits to be asked again after an extension, its row.expires_at can be earlier than the permission's. What lost, gained and pending list are changes: {"set_grant_id", "selector", "cluster_id", "subject_id", "login", "subject_kind", "group_id", "group_name", "role", "scope", "expires_at"}, plus code and params when a rule, not the set, took the permission away.

The errors are in Errors.

Access requests¶

A person asks for a role on a cluster or a namespace for a while, with a reason and maybe a ticket, and an administrator approves or denies it; a cluster's environment can grant some roles without approval (auto_approve_roles, in Environments). The permission an approval gives lasts from the approval, and its grant.create carries request_id (Audit). Filing a request is Pro (403 edition.feature in Free, and with a lapsed key); deciding what waits is not. Any enabled administrator other than the person who asked decides. The same routes serve the join requests of people without an account (Onboarding), which only an administrator reaches.

A request for a role is {"id", "kind": "access", "status", "subject_id", "login", "name", "cluster_id", "cluster_name", "role", "scope", "duration_seconds", "reason", "ticket", "origin", "origin_detail", "needs_admin", "extends_grant_id", "created_at", "expires_at", "decided_by", "decided_as", "decided_at", "decision_note", "result_grant_id", "granted_until"}:

• status is pending, approved, denied, expired or cancelled. A request waits 24 hours (expires_at), and one past them reads expired at once.
• scope is a namespace or * for the whole cluster; duration_seconds is what it asks for, counted from the approval.
• origin is where it was filed: web, cli, forbidden (the link of a cluster's 403, with the refused request in origin_detail, printable ASCII only) or notice.
• needs_admin says only an administrator may decide it; extends_grant_id names the direct permission of the same role and scope that an approval extends instead of granting anew (null otherwise).
• decided_by is {"id", "login", "name"}, null until a person decides; decided_as is admin, or policy for the environment's rule, with decided_by null. decision_note is what the person who decided wrote for the person who asked, result_grant_id the permission an approval created or extended and granted_until its end.

The errors are in Errors.

Owners¶

An administrator names the owners of an environment, a cluster, a namespace of a cluster or a group. Naming one is Pro (403 edition.feature in Free and with a lapsed key); listing and removing them work in every edition.

A scope is {"kind": "environment", "environment_id"}, {"kind": "cluster", "cluster_id", "cluster_name"}, {"kind": "namespace", "cluster_id", "cluster_name", "namespace"} or {"kind": "group", "group_id", "group_name"}. An owner is {"id", "scope", "owner", "inherited", "created_by_login", "created_at"}, where owner is a person, {"subject_id", "login", "display_name", "disabled"}, or a group, {"group_id", "group_name", "members"}, and inherited marks an environment's owner listed on one of its clusters.

The errors are in Errors.

Groups¶

A group is a named set of people and bots with permissions of its own; each member gets those permissions as derived rows of /api/grants (source.kind group). An administrator uses every route. In Pro, the owners of a group read it (GET /api/groups lists only the groups they own, without member; another group's GET /api/groups/{id} is 404 group.not_found) and add, extend, move and remove its members; the owners of a place add, extend and revoke group permissions there. Within their limits: outside what they manage 403 owner.out_of_scope, giving themselves access (adding or moving themselves, lengthening their own membership, a group permission for a group they are a member of) 403 owner.self, a bot added, moved or lengthened and a native role's group permission 403 owner.admin_only, and the members of a group that owns something 409 owner.group_owns with params.scope. Anyone else gets 403 session.admin_only before the body is read. Creating, renaming and deleting a group stay an administrator's. Owners' events carry "as": "owner" and owner_scope.

A failing entry of a batch answers with its position in params.index; a permission that a set put on a group, named in a group batch, is refused with 409 grant.set_derived.

Bulk operations¶

Revoking, removing and disabling in bulk share one contract. Each route takes {"ids": [...], "reason": "..."}:

• ids: from 1 to 500, none repeated. They are the ids of the rows the list shows: the permission, the membership (id in members_list, not the account's), the group permission or the account.
• reason: optional, at most 500 characters.

The answer is 200 with {"batch_id", "<items>", "unchanged": [...]}. batch_id is a uuid. <items> is grants, members or subjects, each as its list returns it, in the order asked and without the unchanged ones. unchanged holds the ids that were already done (a permission already revoked, a member already removed, an account already disabled): they are not a failure, and each still writes its row in the control log.

A batch is all or nothing. A request with the wrong shape is 400 before anything is read: batch.size for no ids or more than 500, batch.duplicate for a repeated id (params.index is the position of its second occurrence and params.id the id) and batch.reason_too_long. An item that fails answers with the status and the code its single operation answers, plus params.index (its position in the request, from 0) and params.id, and nothing changes. The policies are the single operation's: a batch refuses what one at a time would refuse.

Every item writes a row in the control plane log with the action its single operation writes, plus batch (the uuid), batch_size (the ids asked) and reason when one was given; a row of an unchanged item carries unchanged: true. After the commit, each affected cluster is reconciled once.

Extending in bulk (POST /api/grants/extend, and a group's members/extend and grants/extend) follows the same contract with three differences. It takes from 1 to 50 ids. Besides ids and reason it takes one decision for all, exactly one of extend_by_seconds, expires_at and never_expires: otherwise 400 batch.extend_choice, after the checks above. Its answer carries changes, each item's expiry before and after, instead of unchanged.

Moving members to another group (a group's members/move) follows the contract of removals, with moved, the new memberships, for <items>, and in unchanged the members who were in the destination already. Each member writes two rows: group.member.remove in the group it leaves, with to_group_id, and group.member.add in the one it joins, with from_group_id; a member who was there already writes its group.member.add row with unchanged: true. The control plane log shows the batch in one line, as a move between groups.

Roles¶

A role is what a permission grants: one of the six system roles (the tiers), a custom role or a native role. Custom roles are composed from the capability catalogue plus advanced rules ({"apiGroups", "resources", "verbs", "resourceNames"?}). A native role names groups the cluster already knows, in groups, and nothing else.

A permission can name a custom role in POST /api/grants. Besides the checks of a system role: 422 grant.unknown_role for an unknown or deleted role, 422 grant.role_not_on_cluster if the role is limited to other clusters, 422 grant.role_namespace_only for scope * on a role that cannot be granted to a whole cluster, and 409 grant.cluster_bootstrap_v1 if the cluster still has the previous bootstrap manifest. A native role also answers 422 grant.role_cluster_only for a namespace scope. When the role is native, can be privileged on its own (developer, debugger, admin, secrets-reader or a custom role that runs workloads or reads or writes Secrets), or the cluster's identity template isn't the default, granting reads the cluster's RBAC live: 422 grant.privileged_ttl when a name the permission gives has privileged access (a group of the role, the person's name, or kubelatch's group of the role on its scope) and the expiry is missing or beyond 8 hours, 409 grant.identity_collision when the template gives the person a name another account already has there, and 502 cluster.unreachable when the cluster can't be read. The same applies to POST /api/grants/batch.

Credentials¶

kubelatch CLI¶

AI agents¶

The sessions and approvals of AI agents (the routes and fields call an approval a request), and a person's consent to a delegated agent. An administrator sees every account's; anyone else, their own (404 for someone else's). None of these routes takes a CLI token: deciding and consenting need a browser session. See AI agents.

The three authorizations routes exist only while KUBELATCH_MCP_ENABLED is true.

Edition¶

All require admin.

GET /api/me carries edition (free or pro) for everyone. A registration beyond a limit (POST /api/subjects for a person, POST /api/subjects/{id}/enable on a person, POST /api/clusters, POST /api/roles and PUT /api/roles/{id}, except for a native role) answers 422 edition.limit with resource, max and edition. In Free and lapsed instances, GET /api/audit, GET /api/audit/summary and GET /api/control-events serve the last 24 hours and carry floor, the earliest moment served (null otherwise); GET /api/audit/{id} answers 404 for an older event, the same as for an unknown id.

Webhooks¶

All require admin. Webhooks are Pro: outside it, creating, changing and testing one answer 403 edition.feature, while listing them, their deliveries and deleting them work in any edition.

404 webhook.not_found for an unknown id. A body that doesn't pass answers 400: webhook.bad_name (1 to 80 characters without control characters, params.max), webhook.bad_url (not an https URL with a host, without a user or a fragment, of at most 2,048 bytes), webhook.private_url (the host is localhost or an address that isn't public, unless KUBELATCH_WEBHOOK_ALLOW_PRIVATE is true), webhook.bad_format, webhook.bad_locale or webhook.bad_events (none, or one that isn't one of the four).

Audit¶

By default /api/audit hides rows with no resource (API discovery and authentication failures); include_discovery=true shows them. outcome keeps one class of result: denied (401 or 403), error (5xx, or an error after a success status, such as a stream the cluster reset) or write (create, update, patch, delete, deletecollection, or an exec, attach or port-forward). Any other value is 400 query.bad_filter. The summary's denied, errors and writes count exactly the rows these three values select. access keeps one kind of sensitive access, allowed and denied alike: exec (the exec and attach subresources), secrets (get, list or watch on Secrets) or portforward; any other value is 400 query.bad_access. It is the definition behind the sensitive counts of GET /api/insights, so each of those counts is the number of rows its value selects. environment (an environment's id) keeps the requests of the clusters that environment holds today, not the ones it held when the request was made, and production=true those of every environment marked as production (none marked, nothing; a production environment with no cluster keeps nothing, never every cluster). Both listings take them; anyone without the admin role gets 403 session.admin_only for either, whatever its value. An environment that is not the id of an existing environment, a production other than true, or both together is 400 query.bad_environment. Both listings return events, page, page_size, has_more and floor (Edition). Each request carries impersonated_user, the name the proxy sent the cluster for it (Impersonate-User), empty for a request refused before that name was worked out.

CI trust rules¶

All require admin.

Web interface¶

Any other route serves the embedded SPA: the file if it exists, or index.html for interface routes (/login, /account-link, /account, /activity, /cli/…, /admin/…, /agents/…). A missing file under /assets/ is 404. It only accepts GET and HEAD.