Authentication Pro
The REST API authenticates with a workspace token sent as a bearer header. (The MCP server uses the same token, and additionally supports OAuth for agent clients.)
Workspace tokens
A workspace API token is a long-lived secret you create yourself. It's scoped to a single workspace and carries that workspace's permissions - treat it like a password. Send it as a bearer header on every request:
curl https://canopy.8starlabs.com/api/v1/maps \
-H "Authorization: Bearer $CANOPY_TOKEN"The same token works for the MCP server - see Connect with a token.
Create a token
Only the workspace owner can create, view, or revoke API tokens - Admins, Editors, and Viewers can't. Create one in Settings → Workspace → API tokens:
Open API tokens
Go to Dashboard → Settings → Workspace → API tokens. Tokens belong to the workspace you have open, so switch workspaces first if you need a different one.
Name it + set an expiry
Give it a name (e.g. CI pipeline), pick an expiry (never, or 30–365
days), and click Create. The secret - cnpy_live_… - is shown once;
copy it immediately, since only a SHA‑256 hash is stored.
Use it
Send it as a bearer token (above), stored in an env var like CANOPY_TOKEN
- never commit it to source control.
Anyone holding a token can read and write that workspace's maps. If one leaks, revoke it right away and create a replacement.
A workspace can hold up to 10 active tokens at once - revoke one to free a slot.
Revoke a token
Open Settings → Workspace → API, find the
token, and click Revoke. It stops working immediately and everywhere - the
next request from the REST API or any MCP client using it
returns 401 invalid_token. To rotate, create a new token, update your
client, then revoke the old one.
CI pipeline
cnpy_live_••••a1b2 · Never expires
For browser-based sign-in instead of a pasted token, see OAuth for MCP clients (read-only).