Authentication & API tokens
Colophon’s delivery API needs no credential: published content is public. Everything else, reading drafts and writing, needs one. Scripts, site builds and other tools use a project API token; people use their own sign-in.
Which credential goes where
Section titled “Which credential goes where”| Credential | Looks like | Who it is | Works on |
|---|---|---|---|
| None | Anyone | The delivery API (/content/v1), media (/media/v1), /version, /openapi.json, /livez, /readyz |
|
| Project API token | colophon_api_ and 43 more characters |
The token itself, an identity of its own | Its own project’s content routes, /api/v1/projects/{project}/environments/{environment}/…, and POST /api/v1/rich-text/validate |
| Personal access token | an opaque string from colophon login |
A person, with their roles | Every management route that person may use, for 30 days |
| Browser session | the colophon_session cookie |
A person signed in to the Studio | Every management route; writes also need X-CSRF-Token and a trusted Origin |
| Site user session | a bearer token or the colophon_audience cookie |
One of your website’s visitors | Gated content on the delivery API, and the audience routes |
| Preview token | cpv_ and more |
Whoever opened the preview | /preview/v1, for one entry or publish request, for 15 minutes |
This page is about the first three. Site user sessions are covered with gated content; preview tokens with Preview.
Send the token in the Authorization header
Section titled “Send the token in the Authorization header”Every token goes in one header, the same way for every route that takes it:
Authorization: Bearer colophon_api_…There is no query-string form and no custom header: a credential in a URL ends up in logs and browser history.
The management API. Ask the server what this token may do:
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/permissions" \ -H "Authorization: Bearer $COLOPHON_TOKEN"Response: 200 OK, a full-access token’s permissions
HTTP/1.1 200 OKcontent-type: application/jsonx-request-id: 01a1ee74-3bf3-7597-a87a-abcbcf101b69content-length: 392date: Wed, 18 Nov 2026 11:39:17 GMT
{ "data": { "kind": "token", "role": null, "permissions": [ { "action": "content.read", "subject": "*" }, { "action": "content.create", "subject": "*" }, { "action": "content.update", "subject": "*" }, { "action": "content.delete", "subject": "*" }, { "action": "content.review", "subject": "*" }, { "action": "content.publish", "subject": "*" }, { "action": "schema.change", "subject": "*" }, { "action": "destinations.manage", "subject": "*" } ] }}GraphQL takes the same header on POST …/collections/{collection}/graphql:
curl "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/graphql" \ -H "Authorization: Bearer $COLOPHON_TOKEN" \ -H "Content-Type: application/json" \ -d '{"query": "{ entries(first: 5) { nodes { id title } } }"}'Live events too, on the signed-in stream (curl -N keeps the stream open):
curl -N "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/events" \ -H "Authorization: Bearer $COLOPHON_TOKEN"The delivery API takes no token. If you send one anyway it is ignored and the read is anonymous; it never unlocks drafts or gated content.
The SDK attaches it for you: new Client({ baseUrl, token: process.env.COLOPHON_TOKEN }).
Project API tokens
Section titled “Project API tokens”A project API token belongs to one project. It holds permissions the way a role does, it ends on a date you choose, and anything it writes is recorded as written by that token, not by the person who made it.
Make one in the Studio
Section titled “Make one in the Studio”You need a role that manages API tokens; owners do by default.
- Open the project’s Settings → API tokens and press New token.
- Give it a Name that says what uses it (
Site build,Import script): it is how you’ll know which one to revoke. A Description is optional. - Choose What it may do: Read only, Full access or Custom (below).
- Choose how long it Works for: 7 days, 30 days, 90 days, 6 months or a year.
- Press Make the token, then Copy the token. It is shown once: Colophon stores only its SHA-256 fingerprint, so a lost token can’t be shown again. Revoke it and make another.
The list shows each token’s state (Active, Ended or Revoked), what it may do, when it was last used, when it stops working and who made it.
What a token may do
Section titled “What a token may do”| In the Studio | kind in the API |
Permissions |
|---|---|---|
| Read only | read-only |
content.read on every content type: sees every entry, drafts included, and changes nothing |
| Full access | full-access |
Every action a token may hold, on everything: content.read, content.create, content.update, content.delete, content.review, content.publish, schema.change, destinations.manage |
| Custom | custom |
Exactly the permissions you list, each for every content type (*) or one content type, optionally narrowed to some fields or to the token’s own entries |
A token can never hold more than the person making it may do. Making a token with a power your role lacks is
refused with 403 and details.reason cannot_grant.
How long it lasts
Section titled “How long it lasts”Between 1 and 366 days (expires_in_days); the Studio offers 7, 30, 90, 180 and 365. After that the token
answers 401 unauthorized, exactly as a revoked one does, and the Studio shows it as Ended. To replace a
token without downtime, make the new one, switch your site or script to it, then revoke the old one.
A project holds at most 100 active tokens; one more is refused with 422 and too_many_tokens.
Make one with the API
Section titled “Make one with the API”The token routes are for people: they take a personal access token or a browser session, never an API token. Here the project’s owner makes a read-only token for a nightly site build:
curl -i -X POST "http://localhost:8080/api/v1/projects/$PROJECT/tokens" \ -H "Authorization: Bearer $PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"name": "Nightly build", "kind": "read-only", "expires_in_days": 30}'Response: 201 Created, with the secret
HTTP/1.1 201 Createdcontent-type: application/jsonx-request-id: 01a1ee74-3c85-767b-b1c0-c10310722d09content-length: 527date: Wed, 18 Nov 2026 11:39:17 GMT
{ "data": { "id": "01a1ee74-3c87-7615-b145-77e406400537", "identity_id": "01a1ee74-3c87-7615-b145-77e5fe9fe634", "name": "Nightly build", "description": "", "kind": "read-only", "permissions": [ { "action": "content.read", "subject": "*" } ], "state": "active", "created_by": { "id": "01a1ee74-2549-74be-9e59-754b0adafad3", "name": "Akira Shirase" }, "created_at": "2026-11-18T11:39:17.511009Z", "expires_at": "2026-12-18T11:39:17.511884Z", "last_used_at": null, "revoked_at": null, "limits": null, "secret": "colophon_api_LGoSTqAWrhLQl7L67mVV97EV0qJCsyHL84u-Mfxq5QY" }}secret appears in this answer and nowhere else. Keep it, and the token’s id, for the steps below:
export BUILD_TOKEN='colophon_api_…' # data.secretexport BUILD_TOKEN_ID='…' # data.idPERSONAL_TOKEN here is the owner’s personal access token. colophon login --server http://localhost:8080
gets one through a browser approval and keeps it in ~/.config/colophon/credentials.json; see CLI.
A custom token lists its permissions. Each is an action and a subject (* or a content type’s
address name), with optional fields and condition: "own". This one may read recipes and create new ones,
and nothing else:
{ "name": "Recipe importer", "kind": "custom", "expires_in_days": 7, "permissions": [ { "action": "content.read", "subject": "recipes" }, { "action": "content.create", "subject": "recipes" } ]}Limits
Section titled “Limits”A token can also carry ceilings on its own work, as limits when it is made or later with PATCH. The Studio
doesn’t set them yet; use the API.
| Limit | Range | What happens over it |
|---|---|---|
requests_per_minute |
1 to 100,000 | 429 rate_limited with Retry-After, before the request does any work |
documents_per_day |
1 to 1,000,000 | Entry creates, saves, translations and imported items over it: 403 with budget_exceeded |
max_concurrent_jobs |
1 to 64 | A publish whose website deliveries would hold more jobs at once: 403 with budget_exceeded |
tokens_per_day, cost_per_day_micros |
1 to 1,000,000,000; 1 to 100,000,000,000 | Ceilings for AI model calls, in model tokens and in millionths of a currency unit. Accepted and stored; nothing in Colophon spends against them yet |
Days and minutes are rolling windows. A limit you leave out is unconstrained; {"limits": null} removes them
all. Give the nightly build token a ceiling of two requests a minute:
curl -s -X PATCH "http://localhost:8080/api/v1/projects/$PROJECT/tokens/$BUILD_TOKEN_ID" \ -H "Authorization: Bearer $PERSONAL_TOKEN" \ -H "Content-Type: application/json" \ -d '{"limits": {"requests_per_minute": 2}}' | grep -o '"limits":{[^}]*}'"limits":{"documents_per_day":null,"max_concurrent_jobs":null,"requests_per_minute":2,"tokens_per_day":null,"cost_per_day_micros":null}Three reads in a row: the third is over the ceiling.
for attempt in 1 2 3; do curl -s -o /dev/null -w "%{http_code}\n" \ "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $BUILD_TOKEN"done200200429The refusal says when to try again, in seconds:
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $BUILD_TOKEN"HTTP/1.1 429 Too Many Requestscontent-type: application/jsonretry-after: 30x-request-id: 01a1ee74-3cf5-75b9-9fc9-28e8a1c17f35content-length: 191date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "rate_limited", "message": "too many requests; try again in 30 second(s)", "details": { "reason": "rate_limited", "pointer": "" }, "request_id": "01a1ee74-3cf5-75b9-9fc9-28e8a1c17f35" }}A token can’t read or change its own limits. A person reads them, with what the token has used, from
GET /api/v1/projects/{project}/tokens/{token} (limits and usage). Every change to a token’s limits is
recorded in the project’s activity log, and so is the first refusal of each run of refusals.
Revoke a token
Section titled “Revoke a token”In the Studio, press Revoke beside the token and confirm with Revoke it. With the API, a person sends
DELETE:
curl -s -X DELETE "http://localhost:8080/api/v1/projects/$PROJECT/tokens/$BUILD_TOKEN_ID" \ -H "Authorization: Bearer $PERSONAL_TOKEN" | grep -o '"state":"[a-z]*"'"state":"revoked"Revoking is exact. It waits for requests already running under the token to finish, and once it has committed no new request starts: the next one is refused.
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $BUILD_TOKEN"HTTP/1.1 401 Unauthorizedcontent-type: application/jsonx-request-id: 01a1ee74-3d18-7462-a7f9-a90242bb3782content-length: 111date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "unauthorized", "message": "sign in first", "request_id": "01a1ee74-3d18-7462-a7f9-a90242bb3782" }}What the token already did stays in the activity log, under its name. Revoking can’t be undone.
What a token can never do
Section titled “What a token can never do”A token is for content. These stay with people, whatever the token’s kind:
- Manage access, or read the record of it. No token may hold
members.manage,roles.manage,tokens.manageoraudit.read, and the database refuses them too. A leaked token can’t make another token, invite anyone, raise a role or read what it did. - Use the people routes:
/me, the project list, members, invitations, roles, tokens and the activity log answer403withapi_token_not_allowed. - Approve a publish request that a token sent for review. Any token approving any token’s request is
refused with
403andagent_self_review: a person has to approve. A token may still publish a request a person approved, and may request changes. See Management API. - Schedule a publish. A schedule runs later as the person who made it, so tokens get
api_token_not_allowed. - Open a preview. Previews show drafts to people; tokens are refused.
- Reach another project. Another project’s routes answer
404, the same as a project that doesn’t exist, so a token can’t find out what else is on the server. - Do more than its maker. A token never holds a power its maker’s role didn’t have when it was made.
A token on a people route:
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/members" \ -H "Authorization: Bearer $COLOPHON_TOKEN"HTTP/1.1 403 Forbiddencontent-type: application/jsonx-request-id: 01a1ee74-3d27-7348-b93d-7dd515862d84content-length: 262date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "forbidden", "message": "an API token works only with its project's content; members, roles, tokens and the audit log stay with people", "details": { "reason": "api_token_not_allowed", "pointer": "" }, "request_id": "01a1ee74-3d27-7348-b93d-7dd515862d84" }}A token on a project that isn’t its own:
curl -i "http://localhost:8080/api/v1/projects/01a1ee5f-0000-7000-8000-000000000000/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $COLOPHON_TOKEN"HTTP/1.1 404 Not Foundcontent-type: application/jsonx-request-id: 01a1ee74-3d37-72f0-9a51-5da251070a78content-length: 111date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "not_found", "message": "no such resource", "request_id": "01a1ee74-3d37-72f0-9a51-5da251070a78" }}Keep tokens on a server
Section titled “Keep tokens on a server”A token is a password for your project’s content. Treat it like one:
- Put it in a server’s environment or a secret store, and read it from there (
process.env.COLOPHON_TOKEN). Never commit it, and never put it in front-end code, a browser bundle, a mobile app or a public build log. - A website reads published content from the delivery API with no token. If a page needs drafts, render it on a server; to show editors a draft on the site, use Preview, whose tokens are short-lived and read one entry.
- Give each script or site its own token with the least it needs, so you can revoke one without stopping the rest. Prefer Read only or Custom over Full access, and short lifetimes over long ones.
- The
colophon_api_prefix lets secret scanners recognise a leaked token. If one leaks, revoke it at once and check the activity log for what it did.
Rate limits
Section titled “Rate limits”Every server counts requests, shared across servers through Valkey when there are several:
| Counted per | Covers | Default |
|---|---|---|
| Client address | The management API and sign-in (/api/, /auth/) |
300 requests a second, bursts of 600 |
| Credential | The same routes, per token, cookie or personal token | 150 requests a second, bursts of 300 |
| Client address | The delivery API (/content/) |
1,000 requests a second, bursts of 2,000 |
Over a limit, the answer is 429 with rate_limited and a Retry-After header, before the request does any
work. A token’s own requests_per_minute applies on top. Health checks, /version and the Studio’s files are
never counted. Operators change these; see Rate limits.
The errors you will get
Section titled “The errors you will get”Every refusal is the same envelope: code for the kind, details.reason where there is one, a message safe to
show a person, and the request id. Branch on code and details.reason.
| Status | code |
details.reason |
When |
|---|---|---|---|
401 |
unauthorized |
No credential, a malformed or unknown one, a revoked or expired token | |
403 |
forbidden |
api_token_not_allowed |
A token on a people route, scheduling or previews |
403 |
forbidden |
missing_permission |
The token lacks the permission; details.permission names it |
403 |
forbidden |
agent_self_review |
A token approving a publish request a token sent |
403 |
forbidden |
budget_exceeded |
Over documents_per_day or max_concurrent_jobs |
403 |
forbidden |
cannot_grant |
Making a token with a power you don’t have |
404 |
not_found |
Another project, or something the token may not see | |
422 |
validation_failed |
invalid_expiry, permissions_required, too_many_tokens, invalid_limit |
A token the API refuses to make or change |
429 |
rate_limited |
rate_limited |
Over a rate limit; wait Retry-After seconds |
No credential at all:
curl -i "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries"HTTP/1.1 401 Unauthorizedcontent-type: application/jsonx-request-id: 01a1ee74-3d48-746a-91f9-41238360c59dcontent-length: 111date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "unauthorized", "message": "sign in first", "request_id": "01a1ee74-3d48-746a-91f9-41238360c59d" }}A read-only token trying to write, which also shows details.permission. Make a read-only token in the
Studio and send a create with it:
curl -i -X POST "http://localhost:8080/api/v1/projects/$PROJECT/environments/production/collections/recipes/entries" \ -H "Authorization: Bearer $READ_ONLY_TOKEN" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: create-scones-00001" \ -d '{"dish": "Scones"}'HTTP/1.1 403 Forbiddencontent-type: application/jsonx-request-id: 01a1ee74-3d6c-7367-8172-85f5fd8d1bf5content-length: 215date: Wed, 18 Nov 2026 11:39:17 GMT
{ "error": { "code": "forbidden", "message": "your role can't create entries here", "details": { "reason": "missing_permission", "pointer": "", "permission": "content.create" }, "request_id": "01a1ee74-3d6c-7367-8172-85f5fd8d1bf5" }}The full list of codes is on Errors.
People: personal access tokens and sessions
Section titled “People: personal access tokens and sessions”colophon loginsigns the CLI in through the browser: it shows a code, you approve it in the Studio where you’re signed in, and the CLI receives a personal access token that acts as you for 30 days.colophon logoutrevokes it. The SDK andcurlcan use the same token as a bearer token.- The Studio uses a session cookie. Writes made with a cookie must also send the
colophon_csrfcookie’s value asX-CSRF-Token, from anOriginthe server trusts exactly; bearer tokens need neither, since a browser never attaches them by itself.
Only people can approve their own work where their role allows it, manage access and schedule publishing.