The Kubernetes API lets a script list your organization's PMKS (PrivateMind Kubernetes Service) clusters, download their kubeconfigs and control who can use them. For a first call, get a key as Authentication describes, then list your clusters as in 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. 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, 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:
Authorization: Bearer <ACCESS_KEY_ID>:<SECRET>| Key | What it can do |
|---|---|
| Management key, 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 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. 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 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 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:
export PM_MANAGEMENT_KEY='<ACCESS_KEY_ID>:<SECRET>'
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
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. 409 means they already have one, so change it. 404 means they aren't in your organization yet: a new hire signs in to PrivateMind first.
Give a team access
Take the team's id from its page address, here /settings/org/teams/41.
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 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:
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.
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). Save it as a file and run it with bash. It needs curl and jq.
#!/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.
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.
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 |
GET |
/clusters |
Management or personal | List clusters |
GET |
/clusters/{id} |
Management or personal | Read a cluster |
GET |
/clusters/{id}/kubeconfig |
Management or personal | Download a kubeconfig |
GET |
/clusters/{id}/access-entries |
Management | List entries |
POST |
/clusters/{id}/access-entries |
Management | Add an entry |
GET |
/clusters/{id}/access-entries/{user_id} |
Management | Read an entry |
PATCH |
/clusters/{id}/access-entries/{user_id} |
Management | Change an entry |
DELETE |
/clusters/{id}/access-entries/{user_id} |
Management | 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=<id> and each group is the exact string to bind on that cluster, as in the cluster's groups. A cluster_id your key can't see answers 404 with No such cluster.
curl -s https://privatemind.com/api/v1/kubernetes/roles \
-H "Authorization: Bearer $PMIND_USER_KEY"{
"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:<cluster-id>: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.
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. |
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 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, 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 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.
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. Unknown parameters are ignored, and a bad value answers 400.
{
"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:
{
"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.
curl -s https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID \
-H "Authorization: Bearer $PM_MANAGEMENT_KEY"{
"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 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:
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-researchOn 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, matching on email. |
| Team | /clusters/{id}/access-entries/groups/{group_id} |
The number in the team's page address, /settings/org/teams/<id>. |
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, 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 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.
curl -s "https://privatemind.com/api/v1/kubernetes/clusters/$CLUSTER_ID/access-entries?limit=100&page=1" \
-H "Authorization: Bearer $PM_MANAGEMENT_KEY"{
"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.
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.
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:
{
"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. An entry that already exists, expired or not, answers 409, so change it. Errors lists every refusal.
Change an entry
PATCH on an entry's path changes it.
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.
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:
{ "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. 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:
{
"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 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 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 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": "<kid>" }. pm kube token <cluster-id> prints one as JSON, with the pass in status.token:
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:<cluster-id>: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. |
{
"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:
curl -s https://privatemind.com/oidc/pmks/.well-known/openid-configuration{
"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:
curl -s https://privatemind.com/oidc/pmks/jwks{
"keys": [
{
"kty": "RSA",
"use": "sig",
"alg": "RS256",
"kid": "<kid>",
"n": "<modulus>",
"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 | 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. 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. |
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. |
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. |
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. |
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 <field>: <text>, or <text> alone for a rule on the whole body. Three messages are fixed:
give exactly one of user_id, email or group_idexpires_at: must be in the future and at most a year aheadnothing 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.