Get API key

API keys

View as Markdown

Create, scope, and revoke the keys your code uses against the PrivateMind API.

An API key lets your code call the PrivateMind API: a script, a notebook, your own backend or the OpenAI SDK. You create and manage keys in the app, on the API Keys page. For the token format and how to send a key with a request, see Authentication.

Where the page lives

Open API Keys in the main sidebar, or go to /api-keys. The page shows:

  • counts of your active, expired and revoked keys, plus total requests, tokens and spend across every key you own
  • a searchable table of your keys with their status, rate limit, usage and expiry
  • a model reference showing what your org can call today

You see only your own keys. Other users in your org have their own. Keys an org admin created for you with the key management API show here too. They carry the admin's email under the name and Inference only as the permissions. You can revoke them like any other key.

Creating a key

Click Create Key. Fill in:

  • Description: required, up to 120 characters. It becomes the key's name in the table. Use something you'd recognise three months from now (Python trading bot, nightly summariser), not test.
  • Expiration: 30 days, 90 days, 6 months or 1 year. The key stops working the moment it expires, with no grace period.
  • Rate limit: requests per minute. Choose 10, 30, 60, 120, 300 or 600, or Organization default for your org's default for new keys: 60 unless PrivateMind has set another. The limit applies to this key alone, over a sliding window. Going over it returns 429.
  • Budget (USD): optional spend cap for this key. Every key you own draws on your one monthly budget, and a cap can only lower the limit for this key. 0 blocks the key. All chat, embedding and tool calls are priced and counted against the cap. Once spend reaches the cap, the key's calls return 402 until the monthly reset or until you create a new key.

Click Create Key, and a dialog shows the secret.

Warning

The secret is shown once. Copy it into your secret store now, then click "I've saved my key". PrivateMind keeps only a SHA-256 hash of it, so we can't recover it for you. If you lose it, revoke the key and create a new one.

The full bearer token has the shape <access_key_id>:<secret>. The Models page shows which models your org can use, and the recommended fast alias for your first request.

Note

You can have up to 5 active keys at a time. The limit is per user, not per org. To create another, revoke or delete one first.

Reading the table

Each row describes one key:

  • Key: the description you gave it and its prefix, the first 12 characters of the access key id. The full id stays hidden, and the secret is never shown again.
  • Status: Active, Expired (past its expiration_date but not revoked) or Revoked.
  • Rate: the key's limit in requests per minute.
  • Usage: running totals of requests and tokens since the key was created.
  • Expires: the expiry date. With 30 days or less left, the cell turns yellow and shows the number of days.

Click a row to open the key's details:

  • request, token, rate and spend stats
  • a budget bar, if the key has a cap
  • its created and expiry dates, the last IP address that used it, and its permissions
  • a Python snippet to copy, filled in with the key's access id

Rotating

You can't rotate a key in place. Create a new key, then revoke the old one:

  1. Create a new key with the same settings (description, rate, budget).
  2. Roll it out to your client, through an environment variable, a secret manager or whatever delivers your secrets.
  3. Confirm the new key is serving traffic: the old key's request counter stops growing and the new key's starts.
  4. Revoke the old key.

The two keys can run side by side for as long as you like. Each has its own rate limit and, if you set one, its own cap. Both still draw on your one monthly budget, so a second key doesn't add to it. The 5-key limit still applies, so you need a free slot to create the new key before you revoke the old one.

Revoking

Click the trash icon on a key's row, or Revoke in its details, then type the key's name to confirm.

Revocation is immediate and permanent: the next request with that key returns 401. If you revoke a key you still need, create a new one.

Note

Revoke a key as soon as you suspect it's exposed: a committed secret, a leaked log, a teammate who is leaving, a forked container image. Rotating costs one redeploy. Not rotating can cost the key's full budget cap, spent by someone you don't know.

Budgets, rate limits, and what your key inherits

Every key you own draws on your own monthly budget. These layers apply as well, and they stack:

Layer Limit Returns when hit
Per-key rate limit rate_limit_rpm from the create dialog 429
Per-key budget budget_usd from the create dialog (optional) 402
Org-level model entitlement Set by your org admin in Settings → Org 404 if your org can't use the model
Org-level monthly budget Set by your org admin; visible on Account Settings 402 once org spend exceeds it

The tightest layer applies. A key with no budget can still be stopped by the org budget, and no key can call a model your org isn't entitled to.

Every chat and embedding response carries that call's token counts in its usage block. For cost, read the key's Usage view or /v1/usage. Rate limits & budgets explains how spend is calculated.

Restricting keys by IP address

You can limit which IP addresses may use an API key. Rules exist at two levels:

  • Organization rules cover every user API key and application key in the organization. Only org admins can set them.
  • Key rules cover one key. You can set them on your own keys, and org admins can set them on the organization's application keys.

Org admins set organization rules in the API access by IP card on the org Settings page, and application key rules on the Application Keys page. Rules for one of your own keys are on the IP Access tab of its details.

Each level has an allowlist and a blocklist. An entry is a single IPv4 or IPv6 address or a CIDR range, with an optional note, and each list holds up to 100 entries. A range written with host bits set is saved as its network, so 203.0.113.7/24 becomes 203.0.113.0/24.

A request is checked against both levels:

  • An empty allowlist means any address.
  • An address on a blocklist is always refused, even if an allowlist includes it.
  • A key's rules can only narrow the organization's rules, never widen them. A key allowlist cannot admit an address the organization allowlist leaves out.
  • Changes take effect within 15 seconds.

Rules apply to API requests that come in over the internet. They do not apply to using PrivateMind in the browser, or to Compliance API keys.

Behind a proxy

If your requests pass through a proxy that adds an X-Forwarded-For header, every address in that header must be allowed, not only the address your traffic leaves from. A blocklisted address anywhere in the header refuses the request. If any rule applies to the key, a request is refused when its X-Forwarded-For header can't be read, for example because an entry isn't a plain IP address.

When a request is refused

A refused request returns 403 with type permission_error. Don't retry it from the same address: it will fail the same way.

JSON
{
  "error": {
    "message": "This IP address is not on your organization's allowlist.",
    "type": "permission_error",
    "code": "permission_error"
  }
}

The message says which rule refused it:

Message Cause
Requests from this IP address are blocked by your organization. The address is on the organization blocklist
Requests from this IP address are blocked for this API key. The address is on the key's blocklist
This IP address is not on your organization's allowlist. The organization has an allowlist and the address is not on it
This IP address is not on this API key's allowlist. The key has an allowlist and the address is not on it
The client IP address could not be determined, and this API key has IP rules. The X-Forwarded-For header could not be read (see Behind a proxy)

On the Messages API the same refusal comes back in that API's error shape, with error.type permission_error. See Errors.

Verifying a key

The quickest check is the Test Key button at the top of the page. It checks a key you paste in by sending a small request to GET /v1/models. Or, from the shell:

cURL
curl -s -o /dev/null -D - "https://api.privatemind.com/v1/models" \
  -H "Authorization: Bearer $PMIND_KEY" | grep -i -E '^HTTP|^x-privatemind-key'

The model list answers even without a valid key, so a 200 alone proves nothing. Read the header:

  • 200 with x-privatemind-key: valid: the key is valid and active.
  • x-privatemind-key: rejected, or a 401: bad credentials, or the key is revoked or expired.
  • 403: the address you called from is not allowed by IP rules.

Where next

  • Authentication: the bearer-token format and how to attach a key to a request
  • Rate limits & budgets: what 429 and 402 look like, and how spend is calculated
  • Account settings: your profile, org info, and monthly budget
  • My usage: spend, activity heatmap, and history rollups for everything across your keys