# Kubernetes API List your organization's clusters and control who can use them over HTTP. The Kubernetes API lets a script list your organization's [PMKS](https://docs.privatemind.com/kubernetes.html) (PrivateMind Kubernetes Service) clusters, download their kubeconfigs and control who can use them. For a first call, get a key as [Authentication](https://docs.privatemind.com/kubernetes-api.html#authentication) describes, then list your clusters as in [Set up](https://docs.privatemind.com/kubernetes-api.html#set-up). An **access entry** gives a person or a team in your organization a role on one cluster, with an optional end date. An entry is **live** until its end date passes, and a person needs a live entry, their own or a team's, to connect. On this API, a cluster is either a whole cluster or your namespaces on a [shared cluster](https://docs.privatemind.com/kubernetes.html#shared-clusters). The `sharing` field says which, and both answer on the same routes. The API is at `https://privatemind.com/api/v1/kubernetes`, not on `api.privatemind.com`, which serves the inference API. Use `kubectl` for anything inside a cluster, such as pods or namespaces. No route creates, resizes or deletes a cluster, or serves the [live view](https://docs.privatemind.com/kubernetes.html#the-live-view), the web app's read-only view of a cluster's health and workloads. ## Authentication Send a key in the `Authorization` header, access key id and secret joined by a colon: ```text Authorization: Bearer : ``` | Key | What it can do | | --- | --- | | [Management key](https://docs.privatemind.com/key-management-api.html#management-keys), which an org admin creates at **Settings → Org → Management Keys** | While its owner is an org admin, see every cluster in your organization and manage access entries. That includes clusters its owner has no entry on. | | Personal API key, from the [**API Keys**](https://docs.privatemind.com/api-keys.html) page | Read the clusters where its owner has a live entry. An org admin's personal key follows the same rule. Access entries answer `403`. | | `Inference only` and `Inference and containers` keys, org application keys | Answer `403`. A key created through the key management API is an `Inference only` key. | | Compliance key | Made for the [Compliance API](https://docs.privatemind.com/audit-logs.html#compliance-api). Current compliance keys answer `403` here. | This API reads no other header. A key sent as `x-api-key`, a browser session and a `pm` token all answer `401`. A [pass](https://docs.privatemind.com/kubernetes.html#how-a-connection-works) is the signed token `pm` fetches so `kubectl` can reach a cluster. No API key can get one. A management key can add an entry for its owner or anyone else in your organization, and that person can then connect through `pm`. Your [audit log](https://docs.privatemind.com/kubernetes-api.html#audit-events) records every such change. ## Common tasks Each task uses a management key, except the last. ### Set up The examples on this page keep a management key in `$PM_MANAGEMENT_KEY` and a personal key in `$PMIND_USER_KEY`, each as the whole `ACCESS_KEY_ID:SECRET` string. `pm kube ls` shows no ids, so look up the cluster's id by name with `jq`: ```bash export PM_MANAGEMENT_KEY=':' CLUSTER_ID=$(curl -s "https://privatemind.com/api/v1/kubernetes/clusters?limit=500" \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ | jq -r '.data[] | select(.name == "research") | .id') ``` ### Give a person access ```bash curl -s -X POST https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "new.hire@example.com", "role": "edit"}' ``` `201` means the entry exists and the person can [connect](https://docs.privatemind.com/kubernetes.html#connect). `409` means they already have one, so [change it](https://docs.privatemind.com/kubernetes-api.html#change-an-entry). `404` means they aren't in your organization yet: a new hire [signs in to PrivateMind first](https://docs.privatemind.com/users-and-teams.html#how-users-get-into-the-org). ### Give a team access Take the team's id from its page address, here `/settings/org/teams/41`. ```bash curl -s -X POST https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ -H "Content-Type: application/json" \ -d '{"group_id": 41, "role": "view"}' ``` `201` means the team's members can connect. [Teams](https://docs.privatemind.com/kubernetes.html#teams) has the rules on which role applies and who can add members afterwards. ### Find a person's user_id Reading, changing and removing an entry all need a `user_id`. Find it in the cluster's entries by email: ```bash curl -s "https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries?limit=500" \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ | jq '.data[] | select(.email == "new.hire@example.com") | .user_id' ``` ### Set, remove or renew an end date All three are the same `PATCH` with a different body. Use `/access-entries/groups/41` for a team. ```bash curl -s -X PATCH https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries/1002 \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ -H "Content-Type: application/json" \ -d '{"expires_at": "2026-12-31T00:00:00Z"}' ``` | To | Body | `200` means | | --- | --- | --- | | Set an end date | `{"expires_at": "2026-12-31T00:00:00Z"}` | The entry now ends at that time. | | Remove an end date | `{"expires_at": null}` | The entry stays live until someone removes it. | | Renew an expired entry | `{"expires_at": "2027-03-31T00:00:00Z"}` | The person can get a pass again. | ### Offboard someone This script walks every cluster, finds the person's own entry by email and removes it. Run it before the person leaves your organization. After that, their entries drop out of lists, so the script can't find them and your audit log shows no removal ([When someone leaves](https://docs.privatemind.com/kubernetes.html#when-someone-leaves)). Save it as a file and run it with `bash`. It needs `curl` and `jq`. ```bash #!/usr/bin/env bash set -eo pipefail EMAIL=new.hire@example.com BASE=https://privatemind.com/api/v1/kubernetes AUTH="Authorization: Bearer $PM_MANAGEMENT_KEY" removed=0 rows() { local page=1 body while :; do body=$(curl -fsS --retry 5 "$BASE$1?limit=500&page=$page" -H "$AUTH") || return 1 jq -c '.data[]' <<<"$body" [ "$(jq '.pagination.has_more' <<<"$body")" = true ] || return 0 page=$((page + 1)) done } clusters=$(rows /clusters | jq -r '.id') for cluster in $clusters; do users=$(rows "/clusters/$cluster/access-entries" | jq --arg email "$EMAIL" \ 'select(.email and (.email | ascii_downcase) == ($email | ascii_downcase)) | .user_id') for user in $users; do status=$(curl -sS --retry 5 -o /dev/null -w '%{http_code}' -X DELETE \ "$BASE/clusters/$cluster/access-entries/$user" -H "$AUTH") case "$status" in 200|404) echo "$cluster: removed $user"; removed=$((removed + 1)) ;; *) echo "$cluster: answered $status" >&2; exit 1 ;; esac done done echo "$removed entries removed" ``` A `404` on the `DELETE` means the entry is already gone, so the script treats it as done. Passes already issued [run out within 15 minutes](https://docs.privatemind.com/kubernetes-api.html#remove-an-entry). The script removes only entries in the person's own name. This API has no team route, so remove their team memberships in the app. ### Download a kubeconfig and use it This one takes the personal key of someone with a role on the cluster. ```bash curl -fsS https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/kubeconfig \ -H "Authorization: Bearer $PMIND_USER_KEY" \ -o pmks-research.yaml pm login KUBECONFIG=$PWD/pmks-research.yaml kubectl get pods ``` `-f` stops a refused call from writing its error into the file. `kubectl` then runs `pm` for a pass, so whoever is signed in to `pm` needs a live entry. ## Routes Paths below are under `/api/v1/kubernetes`. | Method | Path | Key | What it does | | --- | --- | --- | --- | | `GET` | `/roles` | Management or personal | [List the roles](https://docs.privatemind.com/kubernetes-api.html#roles) | | `GET` | `/clusters` | Management or personal | [List clusters](https://docs.privatemind.com/kubernetes-api.html#list-clusters) | | `GET` | `/clusters/{id}` | Management or personal | [Read a cluster](https://docs.privatemind.com/kubernetes-api.html#read-a-cluster) | | `GET` | `/clusters/{id}/kubeconfig` | Management or personal | [Download a kubeconfig](https://docs.privatemind.com/kubernetes-api.html#download-a-kubeconfig) | | `GET` | `/clusters/{id}/access-entries` | Management | [List entries](https://docs.privatemind.com/kubernetes-api.html#list-entries) | | `POST` | `/clusters/{id}/access-entries` | Management | [Add an entry](https://docs.privatemind.com/kubernetes-api.html#add-an-entry) | | `GET` | `/clusters/{id}/access-entries/{user_id}` | Management | [Read an entry](https://docs.privatemind.com/kubernetes-api.html#read-an-entry) | | `PATCH` | `/clusters/{id}/access-entries/{user_id}` | Management | [Change an entry](https://docs.privatemind.com/kubernetes-api.html#change-an-entry) | | `DELETE` | `/clusters/{id}/access-entries/{user_id}` | Management | [Remove an entry](https://docs.privatemind.com/kubernetes-api.html#remove-an-entry) | For a team's entry, use `/access-entries/groups/{group_id}` on the last three routes. Any other path or method, `POST /clusters` included, answers `404` once the key check has passed. `HEAD` on a listed `GET` path behaves as that `GET`. `POST` and `PATCH` take a JSON body with `Content-Type: application/json`. Without that header the call answers `400`. Answers are JSON with the result under `data`, except the kubeconfig, which is YAML. Times come back as ISO 8601 in UTC with milliseconds, such as `2026-10-30T10:00:00.000Z`, whatever offset you sent. ## Roles `GET /roles` lists the three roles, unpaged. Add `?cluster_id=` and each `group` is the exact string to bind on that cluster, as in the cluster's [`groups`](https://docs.privatemind.com/kubernetes-api.html#cluster-fields). A `cluster_id` your key can't see answers `404` with `No such cluster`. ```bash curl -s https://privatemind.com/api/v1/kubernetes/roles \ -H "Authorization: Bearer $PMIND_USER_KEY" ``` ```json { "data": [ { "object": "kubernetes.role", "name": "admin", "group": "pmks:admin", "description": "Administer the customer namespaces on the cluster" }, { "object": "kubernetes.role", "name": "edit", "group": "pmks:edit", "description": "Create and change workloads" }, { "object": "kubernetes.role", "name": "view", "group": "pmks:view", "description": "Read workloads" } ] } ``` | Field | Type | Meaning | | --- | --- | --- | | `object` | string | Always `kubernetes.role`. | | `name` | string | `admin`, `edit` or `view`. This is the value `role` takes everywhere else. | | `group` | string | Without `cluster_id`, the group on a whole cluster with no prefix: `pmks:admin`, `pmks:edit` or `pmks:view`. With it, that cluster's own group, such as `pm:pmks::edit` on a shared cluster. | | `description` | string | One line on what the role is for. | The permissions bound to each group on the cluster decide what the role can do. See [Roles](https://docs.privatemind.com/kubernetes.html#roles). ## Clusters ### Cluster fields | Field | Type | Meaning | | --- | --- | --- | | `id` | string | The cluster id, a lowercase UUID. | | `object` | string | Always `kubernetes.cluster`. | | `name` | string | The name `pm kube login` takes. | | `sharing` | string | `dedicated` for a whole cluster, `shared` for your namespaces on a [shared cluster](https://docs.privatemind.com/kubernetes.html#shared-clusters). | | `region` | string or null | The cluster's region. | | `status.state` | string | `active`, `maintenance`, `suspended`, `provisioning` (being set up) or `retiring` (being removed). [What the page shows](https://docs.privatemind.com/kubernetes.html#what-the-page-shows) explains each. On a shared cluster it also reflects the shared cluster's own state. | | `status.message` | string or null | Any maintenance note. It can be set in any state. | | `endpoint` | string | The address of the cluster's API server. | | `proxy_endpoint` | string or null | The address for [`kubectl` through PrivateMind](https://docs.privatemind.com/kubernetes.html#two-routes-to-a-cluster), or `null` on a direct-only cluster. It uses PrivateMind's public certificate, so `certificate_authority` doesn't apply to it. On a shared cluster the id in it is the shared cluster's. | | `certificate_authority.data` | string or null | The cluster's CA as base64 of the PEM. `null` when none was registered, in which case the cluster's certificate must chain to a CA the client already trusts. | | `namespaces` | array of strings | Your namespaces on a shared cluster, in order. `kubectl` starts in the first. Empty on a whole cluster. | | `groups` | object | The exact group for each role on this cluster, under `admin`, `edit` and `view`, as the cluster sees it. Bind these when you write your own RoleBindings. | | `identity.oidc.issuer` | string | The [issuer](https://docs.privatemind.com/kubernetes-api.html#passes-and-the-issuer) that signs passes. | | `identity.oidc.audience` | string | The id of the shared cluster it runs on, or the cluster id on a whole cluster. It is the `aud` claim of a pass for this cluster. | | `role` | string or null | The caller's own role on the cluster, or `null` if they have none. For an API key the caller is the key's owner. | | `created_at` | string | When the cluster was registered. | | `updated_at` | string | When its record last changed. | ### List clusters `GET /clusters` answers with the clusters your key can see, sorted by name. ```bash curl -s https://privatemind.com/api/v1/kubernetes/clusters \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" ``` Add `status` to list one state only. `limit` and `page` work as in [Pagination](https://docs.privatemind.com/kubernetes-api.html#pagination). Unknown parameters are ignored, and a bad value answers `400`. ```json { "data": [ { "id": "0f8c1c1e-1111-4222-8333-444455556666", "object": "kubernetes.cluster", "name": "research", "sharing": "dedicated", "region": "example-1", "status": { "state": "active", "message": null }, "endpoint": "https://research.example.com:6443", "proxy_endpoint": null, "certificate_authority": { "data": "LS0tLS1CRUdJTi..." }, "namespaces": [], "groups": { "admin": "pmks:admin", "edit": "pmks:edit", "view": "pmks:view" }, "identity": { "oidc": { "issuer": "https://privatemind.com/oidc/pmks", "audience": "0f8c1c1e-1111-4222-8333-444455556666" } }, "role": "edit", "created_at": "2026-10-30T10:00:00.000Z", "updated_at": "2026-10-30T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 100, "total": 1, "has_more": false } } ``` In this shared example, `audience` and the id in `proxy_endpoint` are the shared cluster's id, and `id` is your own: ```json { "id": "7d2e9b40-2222-4333-8444-555566667777", "object": "kubernetes.cluster", "name": "analytics", "sharing": "shared", "status": { "state": "active", "message": null }, "proxy_endpoint": "https://privatemind.com/k8s/a1b2c3d4-3333-4444-8555-666677778888", "namespaces": ["k7q2xm-main", "k7q2xm-batch"], "groups": { "admin": "pm:pmks:7d2e9b40-2222-4333-8444-555566667777:admin", "edit": "pm:pmks:7d2e9b40-2222-4333-8444-555566667777:edit", "view": "pm:pmks:7d2e9b40-2222-4333-8444-555566667777:view" }, "identity": { "oidc": { "issuer": "https://privatemind.com/oidc/pmks", "audience": "a1b2c3d4-3333-4444-8555-666677778888" } }, "...": "..." } ``` ### Read a cluster `GET /clusters/{id}` answers `200` with one cluster. Here the key's owner has no entry on it, so `role` is `null`, and the cluster is in maintenance with a note. ```bash curl -s https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" ``` ```json { "data": { "id": "0f8c1c1e-1111-4222-8333-444455556666", "object": "kubernetes.cluster", "name": "research", "status": { "state": "maintenance", "message": "Planned maintenance until 18:00 UTC" }, "role": null, "...": "..." } } ``` An id that isn't a lowercase UUID, a cluster in another organization and a cluster your key can't see all answer `404` with `No such cluster`, the same as a cluster that doesn't exist. So a key can't discover clusters. ### Download a kubeconfig `GET /clusters/{id}/kubeconfig` answers `200` with YAML. Any key that can see the cluster gets the same file. A suspended cluster still downloads. [Download a kubeconfig and use it](https://docs.privatemind.com/kubernetes-api.html#download-a-kubeconfig-and-use-it) has the call. The answer has `Content-Type: application/yaml; charset=utf-8` and `Content-Disposition: attachment; filename="pmks-research.yaml"`. It holds one cluster, user and context, each named `pmks-` plus the cluster's name: ```yaml apiVersion: v1 kind: Config clusters: - name: pmks-research cluster: server: https://research.example.com:6443 certificate-authority-data: >- LS0tLS1CRUdJTi... users: - name: pmks-research user: exec: apiVersion: client.authentication.k8s.io/v1 command: pm args: - kube - token - 0f8c1c1e-1111-4222-8333-444455556666 interactiveMode: Never installHint: Install the PrivateMind CLI, then run pm login. contexts: - name: pmks-research context: cluster: pmks-research user: pmks-research current-context: pmks-research ``` On a shared cluster the context also has `namespace:` set to the first of `namespaces`. `certificate-authority-data` appears only when a CA was registered. The file holds no secret and connects nobody by itself: whoever uses it needs `pm` on their `PATH` and a live entry. A management key can download it for a cluster its owner has no entry on, and that owner still can't connect. ## Access entries Every route in this section needs a management key. You can add, change and remove entries in any cluster state, suspended included, except `retiring`: a retiring cluster loses its entries when it starts retiring and answers `409` to a new one. An entry belongs to a person or a team, and the path says which: | Holder | Path | Where the id comes from | | --- | --- | --- | | Person | `/clusters/{id}/access-entries/{user_id}` | [List entries](https://docs.privatemind.com/kubernetes-api.html#list-entries), matching on email. | | Team | `/clusters/{id}/access-entries/groups/{group_id}` | The number in the team's page address, `/settings/org/teams/`. | Both ids are positive integers, so an email in the path doesn't work: email works only when you add an entry. On these paths, `404` with `No such cluster` means your key can't see the cluster. `404` with `No such access entry` means the holder has no entry on it, or the id isn't a positive integer. ### Entry fields | Field | Type | Meaning | | --- | --- | --- | | `object` | string | Always `kubernetes.access_entry`. | | `cluster_id` | string | The cluster the entry is on. | | `type` | string | `user` for a person, `group` for a PrivateMind team. | | `user_id` | integer or null | The person's id. `null` on a team's entry. | | `email` | string or null | The person's email. `null` on a team's entry. | | `group_id` | integer or null | The team's id. `null` on a person's entry. | | `group_name` | string or null | The team's name. `null` on a person's entry. | | `role` | string | `admin`, `edit` or `view`. | | `granted_by` | integer or null | The user id of whoever added the entry. Through a management key, that is the key's owner. | | `expires_at` | string or null | The entry's [end date](https://docs.privatemind.com/kubernetes.html#end-dates), or `null` for none. | | `last_connected_at` | string or null | When this entry last produced a pass, or `null` if it never has. [Last connected](https://docs.privatemind.com/kubernetes.html#last-connected) says how to read it. | | `created_at` | string | When the entry was added. | ### List entries `GET /clusters/{id}/access-entries` answers with the cluster's entries, sorted by email or team name. `limit` and `page` work as in [Pagination](https://docs.privatemind.com/kubernetes-api.html#pagination). ```bash curl -s "https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries?limit=100&page=1" \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" ``` ```json { "data": [ { "object": "kubernetes.access_entry", "cluster_id": "0f8c1c1e-1111-4222-8333-444455556666", "type": "group", "user_id": null, "email": null, "group_id": 41, "group_name": "data-platform", "role": "view", "granted_by": 1001, "expires_at": null, "last_connected_at": "2026-10-30T14:12:05.318Z", "created_at": "2026-10-30T10:05:00.000Z" }, { "object": "kubernetes.access_entry", "cluster_id": "0f8c1c1e-1111-4222-8333-444455556666", "type": "user", "user_id": 1002, "email": "new.hire@example.com", "group_id": null, "group_name": null, "role": "edit", "granted_by": 1001, "expires_at": "2026-12-31T00:00:00.000Z", "last_connected_at": null, "created_at": "2026-10-30T10:00:00.000Z" } ], "pagination": { "page": 1, "limit": 100, "total": 2, "has_more": false } } ``` Expired entries stay listed, so compare `expires_at` with the current time if you need only the live ones. ### Read an entry `GET` on an entry's path answers `200` with that entry. ```bash curl -s https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries/groups/41 \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" ``` ### Add an entry `POST /clusters/{id}/access-entries` gives a person or a team a role on the cluster. ```bash curl -s -X POST https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ -H "Content-Type: application/json" \ -d '{"email": "new.hire@example.com", "role": "edit", "expires_at": "2026-12-31T00:00:00Z"}' ``` | Field | Type | Meaning | | --- | --- | --- | | `user_id` | integer | A person in your organization. | | `email` | string | A person in your organization, up to 255 characters. Email matching ignores case. | | `group_id` | integer | A team in your organization. | | `role` | string | Required. `admin`, `edit` or `view`. | | `expires_at` | string or null | Optional. An ISO 8601 date and time with `Z` or an offset such as `+01:00`. In the future and at most 366 days ahead. `null` or leaving it out means no end date. | Send exactly one of `user_id`, `email` or `group_id`. Any other field answers `400`. The answer is `201` with the entry: ```json { "data": { "object": "kubernetes.access_entry", "cluster_id": "0f8c1c1e-1111-4222-8333-444455556666", "type": "user", "user_id": 1002, "email": "new.hire@example.com", "group_id": null, "group_name": null, "role": "edit", "granted_by": 1001, "expires_at": "2026-12-31T00:00:00.000Z", "last_connected_at": null, "created_at": "2026-10-30T10:00:00.000Z" } } ``` Adding a person who isn't in your organization yet answers `404` with `No such user in this organization`: a new hire [signs in to PrivateMind first](https://docs.privatemind.com/users-and-teams.html#how-users-get-into-the-org). An entry that already exists, expired or not, answers `409`, so [change it](https://docs.privatemind.com/kubernetes-api.html#change-an-entry). [Errors](https://docs.privatemind.com/kubernetes-api.html#errors) lists every refusal. ### Change an entry `PATCH` on an entry's path changes it. ```bash curl -s -X PATCH https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries/1002 \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" \ -H "Content-Type: application/json" \ -d '{"role": "view", "expires_at": "2027-03-31T00:00:00Z"}' ``` | Field | Type | Meaning | | --- | --- | --- | | `role` | string | Optional. `admin`, `edit` or `view`. | | `expires_at` | string or null | Optional. The same format and limits as when you add an entry. `null` removes the end date, and leaving the field out keeps the current one. | Send at least one field, or the answer is `400` with `nothing to update`. Any other field answers `400`. The answer is `200` with the whole entry. To renew an expired entry, give it a new `expires_at`. ### Remove an entry `DELETE` on an entry's path removes it. It takes no body. ```bash curl -s -X DELETE https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries/1002 \ -H "Authorization: Bearer $PM_MANAGEMENT_KEY" ``` The answer is `200` with the entry it removed. A pass already issued can't be recalled and runs out within 15 minutes. ## Pagination `GET /clusters` and `GET /clusters/{id}/access-entries` are paged. `limit` is the page size, 1 to 500, default 100. `page` starts at 1, the default. A paged answer has `pagination` next to `data`: ```json { "pagination": { "page": 1, "limit": 100, "total": 7, "has_more": false } } ``` `total` counts every row across all pages. `has_more` is `true` while `page` times `limit` is below `total`. A page past the end answers `200` with an empty `data`. Pages are counted by offset, so removing entries while you walk a list moves later rows up. Read the whole list first, then remove. ## Rate limits Each key has its own limit in requests per minute: 60 for a management key, and for a personal key the [limit set when it was created](https://docs.privatemind.com/api-keys.html#creating-a-key). A key created with no limit takes your organization's default for new keys, 60 unless PrivateMind has set another. | Header | Meaning | | --- | --- | | `x-ratelimit-limit-requests` | The key's limit per minute. | | `x-ratelimit-remaining-requests` | Requests left in the current minute. | | `Retry-After` | Seconds to wait. Only on a `429`. | | `x-ratelimit-reset-requests` | When the next request can go through, as an ISO 8601 time. Only on a `429`. | Over the limit, the answer is `429`: ```json { "success": false, "error": { "message": "Rate limit exceeded. You are sending requests too quickly. Limit: 60 requests per minute.", "type": "rate_limit_error", "code": "rate_limit_exceeded" } } ``` Every request that gets past the key check counts, including a `404` for an unknown route and a `403` for a personal key on access entries. A key refused at the check doesn't count and gets no rate limit headers. ## Retries and idempotency There is no idempotency key, so what a repeated call does depends on the method: | Method | If you send it again | | --- | --- | | `GET` | Safe to repeat. | | `POST` | Answers `409` if the first call worked. After a lost reply, [read the entry](https://docs.privatemind.com/kubernetes-api.html#read-an-entry) to confirm. | | `PATCH` | Sets the same values, answers `200` and writes another audit row. | | `DELETE` | Answers `404` with `No such access entry`. Treat that as done. | On a `429`, wait for `Retry-After`. On a `5xx`, retry reads, and check before retrying a write. ## Audit events Your [audit log](https://docs.privatemind.com/audit-logs.html) records these events: | Event | When | `detail` | | --- | --- | --- | | `pmks_pass_issued` | `pm` gets a pass. | `role`, and on a shared cluster `namespaces` | | `pmks_access_entry_created` | An entry is added. | `target_user_id` or `target_group_id`, `role`, `expires_at` | | `pmks_access_entry_updated` | An entry is changed. | `target_user_id` or `target_group_id`, `role`, `previous_role`, `expires_at`, `previous_expires_at` | | `pmks_access_entry_deleted` | An entry is removed. | `target_user_id` or `target_group_id`, `role` | | `pmks_cluster_registered` | A cluster is registered. | `name`, `sharing`, and on a shared cluster `api_server_id` and `namespaces` | | `pmks_cluster_updated` | A cluster's record changes, or the shared cluster it runs on does. | `name` and `changed`, the sorted names of the fields that changed. When changed, also `previous_name`, and `api_url`, `status`, `proxy_enabled`, `groups_prefix` and `ca_fingerprint` as `{ "from": ..., "to": ... }`. `api_server_id` when the change was to the shared cluster, and `access_entries_removed` when the cluster started being removed with entries on it. | | `pmks_cluster_deregistered` | A cluster is deregistered. | `name`, `access_entries` (how many it had), and on a shared cluster `namespaces` | On all seven, `resource_type` is `kubernetes_cluster` and `resource_id` is the cluster id. The [Compliance API](https://docs.privatemind.com/audit-logs.html#compliance-api) returns `detail` as `metadata`. Who a row names as its actor: - A change made through a key names the key. - A change on the **Access** tab names the person who made it. - A pass names the person who asked for it. - A change PrivateMind staff make to a cluster's record on your behalf names the staff member. The row goes in your organization's log. A change to a shared cluster writes one row for each cluster on it. Each row goes in that cluster's organization's log and names only that cluster. Only successful calls write a row. Reads and kubeconfig downloads write nothing. ## Passes and the issuer This section is for anyone who needs to read a pass or check who signed it. ### What a pass holds A pass is a JWT signed with RS256. Its header is `{ "alg": "RS256", "typ": "JWT", "kid": "" }`. `pm kube token ` prints one as JSON, with the pass in `status.token`: ```bash pm kube token $CLUSTER_ID | jq -r '.status.token' ``` | Claim | Value | | --- | --- | | `iss` | The issuer, `https://privatemind.com/oidc/pmks`. | | `sub` | The person's PrivateMind user id, as a string. | | `aud` | The cluster's `identity.oidc.audience`: the shared cluster's id, or the cluster id on a whole cluster. | | `iat` | When it was issued, in seconds since the epoch. | | `exp` | `iat` plus 900 seconds, or 60 on a live view pass. | | `jti` | A random UUID. | | `email` | The person's email. | | `groups` | One item. On a whole cluster `pmks:admin`, `pmks:edit` or `pmks:view`. On a shared cluster the same with the cluster id in it, such as `pmks::edit`. The cluster adds any prefix, such as `pm:`, when it reads the pass. | | `pmks_cluster` | The cluster id. | | `pmks_user` | The cluster id and the user id joined by a colon. A shared cluster reads it as your username. | ```json { "iss": "https://privatemind.com/oidc/pmks", "sub": "1002", "aud": "0f8c1c1e-1111-4222-8333-444455556666", "iat": 1793354400, "exp": 1793355300, "jti": "5c1e0e5a-7b52-4b7e-9d3a-2f6a8c1d4e77", "email": "new.hire@example.com", "groups": ["pmks:edit"], "pmks_cluster": "0f8c1c1e-1111-4222-8333-444455556666", "pmks_user": "0f8c1c1e-1111-4222-8333-444455556666:1002" } ``` A pass has no `email_verified`, `nbf`, `name` or `preferred_username` claim. The live view reads the cluster with its own pass in the person's name. That pass lasts 60 seconds, always carries the cluster's view group, writes no `pmks_pass_issued` row and doesn't change `last_connected_at`. ### The issuer The issuer is the value in `identity.oidc.issuer`. Its two endpoints take no key, and both answer with `Cache-Control: public, max-age=300`. The discovery document comes first: ```bash curl -s https://privatemind.com/oidc/pmks/.well-known/openid-configuration ``` ```json { "issuer": "https://privatemind.com/oidc/pmks", "jwks_uri": "https://privatemind.com/oidc/pmks/jwks", "response_types_supported": ["id_token"], "subject_types_supported": ["public"], "id_token_signing_alg_values_supported": ["RS256"], "claims_supported": ["sub", "aud", "iss", "iat", "exp", "jti", "email", "groups", "pmks_cluster", "pmks_user"] } ``` The document lists no authorization or token endpoint, because the issuer signs passes and offers no browser login. The public keys are at `/jwks`: ```bash curl -s https://privatemind.com/oidc/pmks/jwks ``` ```json { "keys": [ { "kty": "RSA", "use": "sig", "alg": "RS256", "kid": "", "n": "", "e": "AQAB" } ] } ``` During a rotation more than one key can be listed, and a pass carries the `kid` of the key that signed it. A rotation needs no change on a cluster, because a cluster reads the keys from this address. If the keys can't be read, `/jwks` answers `503` with `Retry-After: 30` and `{ "success": false, "message": "issuer keys unavailable" }`. ## Errors Errors come in three shapes, depending on where the call was refused. Read `error.message`, or `message` when the body has no `error` object. Branch on the status and `error.type`, because message text can change. ### Errors from this API Errors from the API itself have the shape `{ "error": { "type": "...", "message": "..." } }`. | Status | `type` | Message | When | | --- | --- | --- | --- | | `400` | `invalid_request_error` | [Validation message](https://docs.privatemind.com/kubernetes-api.html#validation-messages) | A missing, malformed or unknown field or query value. | | `401` | `authentication_error` | An API key is required: Authorization: Bearer <key> | No key in the `Authorization` header. A key in `x-api-key` and a browser session both land here. | | `403` | `permission_error` | Managing access needs a management key | A personal key on an access entry route. | | `403` | `permission_error` | This key cannot call the Kubernetes API | A compliance key on a `GET`. | | `403` | `permission_error` | The owner of this management key is no longer an org admin | The owner lost the role. The key management API answers this case with `404`. | | `403` | `permission_error` | This management key belongs to a different organization | The key's organization isn't its owner's current one. | | `403` | `permission_error` | This endpoint needs a management key | A management key without the scope such a key normally has. Create a new one. | | `404` | `not_found_error` | No such route | A path or method that isn't listed in [Routes](https://docs.privatemind.com/kubernetes-api.html#routes). A request with no key, or a key refused at the check, gets that refusal first. | | `404` | `not_found_error` | No such cluster | The id isn't a cluster your key can see. See [Read a cluster](https://docs.privatemind.com/kubernetes-api.html#read-a-cluster). | | `404` | `not_found_error` | No such access entry | The id isn't valid, or the holder has no entry on the cluster. | | `404` | `not_found_error` | No such user in this organization | Nobody with that id or email is in your organization, the account is a service identity, or it is being deleted. | | `404` | `not_found_error` | No such group in this organization | No team with that id is in your organization. | | `409` | `conflict_error` | More than one user has that email: use user_id | The email matched two accounts. Add the person on the **Access** tab, where you pick the account. | | `409` | `conflict_error` | That user already has an access entry on this cluster | The person already has an entry, which may be expired. [Change it](https://docs.privatemind.com/kubernetes-api.html#change-an-entry). | | `409` | `conflict_error` | That group already has an access entry on this cluster | The team already has an entry, which may be expired. [Change it](https://docs.privatemind.com/kubernetes-api.html#change-an-entry). | | `409` | `conflict_error` | This cluster is being removed, so it takes no new access entries | The cluster is `retiring`. | ### Refused keys and bad JSON Refused keys and bodies that don't parse use a different shape, `{ "success": false, "message": "..." }`. | Status | Message | When | | --- | --- | --- | | `400` | Error: the request body is not valid JSON | The body doesn't parse. | | `401` | Invalid Bearer token format | The key isn't `ACCESS_KEY_ID:SECRET`. A `pm` token gets this answer. | | `401` | Invalid or expired Bearer token | No such key, or it was revoked. | | `401` | API key has expired | The key has expired. | | `401` | Invalid Bearer token | The secret is wrong. | | `403` | API keys of type 'service_user' cannot be used with the PrivateMind application API | An `Inference and containers` key. | | `403` | This API key is limited to inference and cannot be used with the PrivateMind application API | An `Inference only` key, which includes any application key created through the key management API. | | `403` | This endpoint does not accept application keys | Any other org application key. | | `403` | Compliance keys are read-only | A compliance key on `POST`, `PATCH` or `DELETE`. | | `403` | Your organization only allows PrivateMind from its approved networks, and this request came from <ip>. Connect to your organization's network or VPN and try again. | The request came from outside your organization's approved networks. The body also has `"code": "NETWORK_BLOCKED"` and the address in `client_ip`. When the address can't be determined, the message says so and `client_ip` is `null`. | ### Budget and rate limit A budget or rate limit refusal has the shape `{ "success": false, "error": { "message": "...", "type": "...", "code": "..." } }`. | Status | `type` and `code` | Message | When | | --- | --- | --- | --- | | `402` | `budget_exceeded` | Budget exceeded. This API key has spent $X of its $Y budget. | The key's budget is spent. | | `429` | `rate_limit_error`, `rate_limit_exceeded` | Rate limit exceeded. You are sending requests too quickly. Limit: <n> requests per minute. | Over the key's requests per minute. See [Rate limits](https://docs.privatemind.com/kubernetes-api.html#rate-limits). | Where your organization hides cost, the `402` message reads `Budget exceeded. This API key has used all of its budget.` Either way it goes on to say what to do next. ### Validation messages A `400` reports the first problem it finds, as `: `, or `` alone for a rule on the whole body. Three messages are fixed: - `give exactly one of user_id, email or group_id` - `expires_at: must be in the future and at most a year ahead` - `nothing to update` The rest can change. They look like this: - `role: Invalid option: expected one of "admin"|"edit"|"view"` - `limit: Too big: expected number to be <=500` ### Server errors A `5xx` means something failed on our side. The body is `{ "success": false, "message": "..." }`, sometimes with an `errorId`. If the error persists, quote `errorId` to your account team.