Get API key

Kubernetes API

View as Markdown

List your organization's clusters and control who can use them over HTTP.

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:

Text
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:

cURL
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
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
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
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
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.

cURL
#!/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
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
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:<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
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.

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.

cURL
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 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, 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
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.

cURL
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
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. 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
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
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. 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 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:

cURL
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.
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:

cURL
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:

cURL
curl -s https://privatemind.com/oidc/pmks/jwks
JSON
{
  "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_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.