Developer guide / API keys

Treat keys like credentials

Perminister API keys are server-only machine credentials, separate from human browser sessions and consumer-app sessions.

Key lifecycle

Create and manage keys from the signed-in dashboard.

Create with a narrow scope

Choose product, project, or workspace scope, only the actions needed, and an expiration. The effective authorization is limited by the account's active grants too.

Copy the secret once

The dashboard returns a random bearer key in the creation response. Spaces stores only its SHA-256 verifier; refresh the page and the raw key is gone.

Rotate, expire, or revoke

Create a replacement with the same scope, then revoke the prior key. Expired and revoked keys fail authorization on the next check.

Keep keys on trusted servers

Consumer apps should send keys only from trusted server-side code. Keep them out of browser bundles, source control, URLs, client storage, and logs.

Authorization request

POST /api/authorize
Authorization: Bearer pmk_<uuid>_<secret>
Content-Type: application/json

{
  "productId": "product-id",
  "resourceKind": "project",
  "resourceId": "project-id",
  "action": "read:profile"
}

See permission scopes for evaluation rules and the dashboard to create a key.

Separate human and machine access

Human users sign in through the Perminister browser session.
Consumer applications keep their own app sessions.
Server keys require explicit scope and action checks.

Next: review storage and readiness.