Machine keys

A machine key is a non-human credential with explicit, revocable scope. It’s what your agent uses to authenticate against the control plane. Not your personal API key.

Why the difference matters

If you paste your human credential into your agent, three bad things:

1. If the agent is compromised, your whole account is compromised.
2. You can’t tell what the agent did vs what you did in the audit log.
3. If you rotate your password (or your session expires), the agent breaks.

With a machine key:

• Scope is limited (workspace:read only, workspace:admin controlled, etc.).
• Audit log marks each action with actor=key:<id> — you know what was automated.
• Rotation is independent from your human session.
• Revocation is a click when something goes wrong.

Create a machine key

Via dashboard (recommended for first-time): app.prysmid.com → settings → machine keys → New. Pick name, scope, expiration (or “never expires”). Download the JSON. Won’t be shown again — if you lose it, generate a new one.

Via API:

curl -X POST https://api.prysmid.com/v1/workspaces/$WS/machine-keys \
  -H "Authorization: Bearer $YOUR_HUMAN_TOKEN" \
  -d '{
    "name": "claude-desktop-fernando",
    "scopes": ["workspace:admin"],
    "expires_at": "2027-04-28T00:00:00Z"
  }'

Response (only time the secret is shown):

{
  "id": "mk_abc123",
  "name": "claude-desktop-fernando",
  "scopes": ["workspace:admin"],
  "expires_at": "2027-04-28T00:00:00Z",
  "created_at": "2026-04-28T10:00:00Z",
  "key": {
    "type": "service_account",
    "key_id": "192038...",
    "key_secret": "<long PEM-style string>"
  }
}

Save the full key as local JSON (~/.prysmid/key.json).

Available scopes

Scope	Allows
workspace:read	List and read workspace resources. No writes.
workspace:write	All read + create/edit apps, IdPs, branding, webhooks.
workspace:admin	All write + change plan, create/revoke machine keys, delete workspace (with confirm).
tenant:<slug>:read	Restricted to one tenant, read-only.
tenant:<slug>:write	Restricted to one tenant, R/W.

Tenant-restricted keys are useful when an enterprise customer wants to automate THEIR side via agent without accessing other tenants.

Caution

Start with the lowest scope that works. Trivial to elevate later by generating a new key. Hard to lower once distributed across N agents.

How the agent uses it

The MCP server (@prysmid/mcp) reads the key from PRYSMID_MACHINE_KEY_PATH. It exchanges it for a short-lived access_token (15 min) every time it connects. When calling a tool, it sends the access_token in Authorization: Bearer. The control plane validates scope and signature, then allows or rejects.

You don’t move tokens manually. The machine key is the long-lived secret; the token is ephemeral.

Rotation

curl -X POST https://api.prysmid.com/v1/workspaces/$WS/machine-keys/$KEY_ID/rotate \
  -H "Authorization: Bearer $TOKEN"

Generates a new key with same scope/expiration. Old key stays valid for 24 hours — enough time to update the local JSON across agents without downtime. After 24h the old one auto-revokes.

Immediate revocation

If a key is compromised (committed to a public repo by mistake, laptop stolen, etc.):

curl -X DELETE https://api.prysmid.com/v1/workspaces/$WS/machine-keys/$KEY_ID \
  -H "Authorization: Bearer $TOKEN"

Immediate. Any access_token already issued against that key stays valid for up to 15 more minutes, then bounces. If you need full instant revocation, also ask support to invalidate active tokens.

What machine keys don’t give you

• Not universal passes. They’re per workspace. If you operate 5 workspaces, you have 5 keys (one per workspace) or one “ops” workspace with tenants.
• Don’t enable end-user login. For that you have OIDC + OAuth clients, not machine keys.
• Don’t grant direct low-level instance access. Only the control plane. If you need to operate at a lower level, generate a dedicated service-account key under Settings → Service accounts.

Best practices

• One machine key per integration. Don’t reuse one across 3 agents — if one is compromised, you lose all.
• Explicit expiration. Even though “never expires” is available, default to 1 year. Forces you to review.
• Descriptive naming. claude-desktop-fernando-2026-04 over key1. When you have 20 keys, you’ll thank yourself.
• Periodic audit. keys.list and remove the ones you don’t recognize or remember.