Coline Docs

A workspace API key lets a server or script call the Coline API without a person signing in. Each key belongs to one workspace, carries a fixed set of scopes, and acts as the workspace rather than as a member.

Create a key

Open the developer console and choose a workspace.
Go to API keys and create a key.
Name the key and pick its scopes.
Copy the key. It's shown once. Coline stores only a hash, so a lost key can't be recovered; revoke it and create a new one.

Only the workspace owner and admins can create or revoke keys. Keys start with col_ws_.

Use a key

Send it as a bearer token:

curl https://coline.app/api/v1/workspaces/acme/sheets \
  -H "Authorization: Bearer col_ws_..."

The workspace in the URL must be the key's workspace, by slug or ID. A key for another workspace gets 403 API_KEY_WORKSPACE_MISMATCH.

What a key can and can't do

A key can call any route whose required scopes it holds. See the endpoint reference for the scope each route needs.

A key has no person behind it, so some routes refuse it with 403 USER_IDENTITY_REQUIRED:

calendar routes, which act on a person's calendars and invitations
message, DM and thread routes, which only show conversations a person is in (keys can list public channels)
GET /api/v1/me/workspaces and GET /api/v1/oauth/userinfo

Use an OAuth token for those.

Writes made with a key are recorded in the workspace audit log against the key, not a member.

Rate limits

Each key gets 300 read requests and 60 write requests per minute. See rate limits.

Revocation

A key stops working as soon as an admin revokes it in the console. There is no grace period. Rotate a key by creating the new one, deploying it, then revoking the old one.

Keys in the app CLI

The app CLI (coline-app push) reads a key with the apps.write scope from COLINE_API_KEY. Keep keys out of source control and app bundles; set them in your environment or secret store. See develop locally.