Workspace API Keys¶

Workspace API keys require a PRO workspace or higher

Creating workspace API keys is a paid feature. See Plans & Limits for the full feature matrix.

Workspace API keys are long-lived credentials that authenticate the workspace itself rather than an individual user. They are the right choice for shared back-office automation — sync jobs, reporting pipelines, or internal tools — that operates on workspace-wide data and should keep working regardless of which member set it up.

Workspace key vs. Personal Access Token

A Personal Access Token acts as you, is bounded by your own grants, and cannot carry workspace scopes. A workspace key acts as the workspace at a fixed WORKSPACE_ADMIN permission level, is not tied to any user, and is the only way to grant workspace scopes (workspace:read, workspace:write). Use a workspace key when the automation belongs to the team, not to a person.

Workspace keys are prefixed cto_wk_v1_ and are sent like any other bearer credential:

Authorization: Bearer cto_wk_v1_...

Permission model¶

A workspace key always authenticates at the WORKSPACE_ADMIN role — no more, no less. It cannot be elevated to WORKSPACE_OWNER, and it does not impersonate a user: requests carry no user identity, only the workspace and the key's scopes. Endpoints that require an owner, or that act on a specific user's personal data, are therefore not accessible with a workspace key.

Scopes¶

Workspace keys may only be granted workspace:read or workspace:write. They cannot be given user-scoped scopes such as meetings:* or action-items:*.

Scope	Grants
`workspace:read`	Read workspace settings and members
`workspace:write`	Manage workspace settings, members, API keys, and webhooks (also required to list API keys and webhooks)

A request whose key is missing a required scope returns 403 insufficient_scope.

Issue a key¶

Workspace keys are issued from the Contio app under Settings → Developer → API Tokens (/settings/developer/tokens), by a workspace admin or owner. Issuance is not exposed on the /v1 API. Choose a name, select the scopes the automation needs, and pick an expiry of 30, 60, 90, 180, or 365 days.

Shown once

The plaintext key is displayed exactly once, at creation time. Store it securely (e.g. a secrets manager). If you lose it, revoke the key and issue a new one — it cannot be recovered.

List keys¶

GET /v1/workspace/api-keys returns the workspace's non-revoked keys. Only a masked prefix (e.g. cto_wk_v1_abc...) is returned — never the full key. Requires the workspace:write scope.

curl "https://api.contio.ai/v1/workspace/api-keys?limit=20&offset=0" \
  -H "Authorization: Bearer $CONTIO_WORKSPACE_KEY"

{
  "items": [
    {
      "id": "b2c1...",
      "name": "reporting-sync",
      "prefix": "cto_wk_v1_abc...",
      "scopes": ["workspace:read"],
      "created_at": "2026-07-05T00:00:00Z",
      "expires_at": "2026-10-03T00:00:00Z",
      "last_used_at": "2026-07-10T12:00:00Z"
    }
  ],
  "total": 1,
  "limit": 20,
  "offset": 0
}

Revoke a key¶

DELETE /v1/workspace/api-keys/{id} immediately revokes a key by its ID. Requires the workspace:write scope. Any subsequent request presenting a revoked key is rejected with 401 invalid_token. A successful revoke returns 204 No Content.

curl -X DELETE https://api.contio.ai/v1/workspace/api-keys/b2c1... \
  -H "Authorization: Bearer $CONTIO_WORKSPACE_KEY"

Expiry¶

Every key has a fixed expiry chosen at issuance (30, 60, 90, 180, or 365 days). Once past its expiry, a key is rejected with 401 invalid_token; there is no renewal — issue a replacement and rotate.

Best practices¶

Scope minimally — grant only the scopes the automation needs.
Set the shortest workable expiry and rotate on a schedule.
One key per workload — separate pipelines so you can revoke one without disrupting the others.
Store as a secret — never commit a workspace key to source control or embed it in client-side code.
Prefer a PAT for user-scoped work — if the automation should act as a specific person (and honour that person's permissions), use a Personal Access Token instead.