API keys

Owners and admins manage keys from Organization settings. Members cannot. A key belongs to one organization. It is not a user session and it cannot issue, rotate, or revoke keys.

What a key can do

Each key stores one or more scopes as claims:

• organization:read
• member:read
• invitation:read
• billing:view
• audit:view

A key only proves identity at apiKey.authenticate. Scopes are stored claims checked there. They do not read organization, members, invitations, billing, or audit data.

Write scopes are not issued. Chat, billing checkout, member changes, and support still require a signed-in session.

Issue, rotate, revoke

Create a key with a name, at least one scope, and an optional expiry. The plaintext secret is returned once, then only a SHA-256 hash is stored. The list shows a short prefix, never the secret.

Rotate replaces the secret on the same key. The previous secret stops working immediately. Revoke rejects the secret and cannot be undone. A revoked name can be reused. An organization can have 25 active keys.

Issuing, rotating, and revoking are written to the organization audit log. The secret is not.

Authenticate

The procedure is apiKey.authenticate. The product mounts oRPC at /rpc, so the request is:

POST /rpc/apiKey/authenticate
Authorization: Bearer sk_...
Content-Type: application/json

{ "json": { "scopes": [] } }

scopes may be empty to prove identity, or a list the key must hold. A missing scope is forbidden. An unknown, expired, or revoked secret is unauthorized, with the same error for each. A successful call updates last used and does not write an audit event. The OpenAPI path on the procedure is documentation metadata; it is not a second HTTP route. Expired keys still count toward the 25-key limit until they are revoked.