API keys
Personal keys that let an agent act as you, narrowed to the scopes you choose.
A key acts as the person who created it, inside one workspace, with only the scopes it was given. It can never do more than its owner can: if you lose the Trail author role or leave the workspace, every key you minted stops working.
Create a key
In Settings → API keys, choose New key. You pick:
| Name | What the key is for, e.g. "Claude Code on my laptop". Shown in the audit log. |
| Scopes | See below. Read and write are on by default. |
| Expiration | 30 days, 90 days, 1 year, or none. Fixed at creation; to change it, create a new key and revoke this one. |
The key is shown once, with ready-to-paste configuration for Claude Code, Cursor, Codex, and curl. Joring stores only a hash, so a lost key is replaced, not recovered.
Keys begin with jor_api_. Treat them like passwords: keep them out of
repositories and shared documents.
Scopes
| Scope | Lets the agent |
|---|---|
trails:read | List and read trails |
trails:write | Create trails, edit drafts, run surfacing tests, restore versions, manage grants |
trails:publish | Publish, unpublish, and archive trails |
Write and publish imply read. Give an agent that only drafts trails:read
and trails:write, and keep publishing for a key you use deliberately, or
for yourself in the console.
Rotation and revocation
To rotate, create the new key, update the agent, then revoke the old one. Revoking is immediate: any request in flight with that key fails.
Owners, Admins, Co-owners, IT admins, and Security admins can switch on All keys in this workspace to see everyone's keys, rename them, and revoke them. They cannot see the secret, which is never stored.
Key creation, renaming, and revocation are written to the audit log under API access.
When a key stops working
| Response | Why |
|---|---|
401 | The key is wrong, revoked, or expired. |
403 insufficient-scope | The key lacks the scope; the response names it. |
403 membership-revoked | The key's owner is no longer a member of the workspace. |
403 forbidden | The owner no longer has the Trail author role. |
403 feature-not-enabled | API access is not turned on for the workspace. |
402 upgrade-required | The workspace's plan does not include API access. |