Creating a key
Choose Create API key to open a short wizard:- Scope — the key’s name, and the level it acts at: Organization (every workspace and project), Workspace (every project in one workspace), or Project (one project). You can only create a key at a level you have access to.
-
Permissions — start from a preset and refine:
- Write — read prompts and skills, create, edit, archive, and publish them, and upload session transcripts.
- Read — read prompts and skills only. This is the default.
- Ingest — upload session transcripts only.
- Custom — pick exactly the permissions you want.
- Review — confirm the key’s scope, permissions, and expiry.
- Reveal — the secret is shown once.
keys:create permission at the chosen scope.
Scoping a key
A key carries a subset of the permission catalog. These are the permissions a key can hold:
Grant only what the machine needs: a CI job that uploads sessions needs
ingest:write, not the ability to publish prompts. A key can never be created with permissions beyond what its creator holds, and no key can be given keys:create, so the keys you create can’t create other keys.
Rotating a key
Rotation issues a replacement key with the same scope, permissions, and expiry, so you can roll the secret without re-granting access. You choose a grace period — immediately, or 1 hour, 24 hours, or 7 days — during which the old secret keeps working, giving you time to deploy the new one before the old one stops. Rotation requireskeys:rotate.
Revoking a key
Revoking a key disables it immediately and permanently — there’s no grace period. Requests presenting a revoked key are rejected. Use rotation, not revocation, when you only need to replace a leaked secret without an outage. Revoking requireskeys:revoke.
Next steps
Roles & permissions
The scopes a key can carry.
Audit logs
Key creation, rotation, and revocation are recorded in the admin audit log.