Authentication

Every Public API request must include a token in the Authorization header using the Bearer scheme:

Authorization: Bearer <token>

Copera accepts three token types. The prefix tells you (and the API) which one you are using.

Token type	Prefix	Identity	Surface
Personal Access Token	cp_pat_	You (the user who created it)	Full API
Integration API Key	cp_key_	The integration (a bot)	Boards + Channels only
MCP OAuth token	cp_oat_	The connected user	Issued by the MCP server

Personal Access Token (cp_pat_)

A Personal Access Token authenticates the API as you. Requests are attributed to your user account and inherit your access within the workspace, gated by the scopes you grant the token. PATs unlock the full API surface — boards, export, docs, drive, search, channels, notifications, workspace, and bookings — and are the recommended choice for scripts, CI pipelines, and personal automation.

How to obtain one

1. Open Workspace Settings → Integrations.
2. Select the Personal Tokens tab.
3. Click Create new token.
4. Set a name, choose the scopes it needs, and set an expiration date (up to 1 year).
5. Copy the token immediately — it is shown only once.

Characteristics

• Workspace-scoped — each token is tied to one workspace.
• Acts as your identity — calls are attributed to you and respect your permissions.
• Expires — up to a maximum of 1 year; expired tokens return 401.
• Scoped — only the scopes you grant are honored.

Example

curl https://api.copera.ai/public/v1/docs/tree \
  -H "Authorization: Bearer cp_pat_your_token_here"

Integration API Key (cp_key_)

An Integration API Key authenticates as an integration (a bot) rather than a specific user. It is the right choice when you want a separate identity that operates independently of any user — for example, a bot that posts to channels or reads board data.

note

Integration API Keys cover boards and channels only. To call docs, drive, search, notifications, workspace, or bookings endpoints, use a Personal Access Token instead.

Characteristics

• Bot identity — requests are attributed to the integration, not a user.
• Boards + channels surface — designed for board and channel endpoints.
• Requires explicit access — the integration must be granted the relevant scopes and added as a participant of the specific channels or boards it needs to reach.

Create an integration and generate its key from Workspace Settings → Integrations.

MCP OAuth token (cp_oat_)

MCP OAuth tokens are issued automatically when an AI client connects to your workspace through the MCP server. You don't create these by hand — the OAuth flow mints them on the user's behalf. They authenticate as the connecting user, scoped to what the MCP integration is allowed to do.

If you are building a direct integration, use a PAT or an Integration API Key. cp_oat_ tokens are part of the MCP connection flow.

Scopes

Scopes control which domains a token can reach. Grant only what your integration needs.

Scope	Grants access to
access_boards	Boards, tables, rows, row comments, row markdown, table export
access_channels	Channels, channel messages, direct messages
access_docs	Documents — read, write, search, tree
access_drive	Drive — browse, search, download, upload, folders
access_notifications	Notifications — list, update, delete
access_bookings	Bookings and booking types

Notes on scope coverage:

• Workspace endpoints (info, members, teams) require a valid PAT for an internal (non-external) user — there is no separate workspace scope.
• Search has no single scope. A search request returns only the entity types your token is allowed to read: documents need access_docs, channels and messages need access_channels, drive items need access_drive. Other types (such as todos and AI chats) are searchable with any valid token.
• Export runs on board tables, so it requires access_boards.

A request to a domain your token lacks the scope for returns 403 Forbidden. See Error Handling.

Security best practices

• Store tokens securely — use environment variables or a secret manager. Never hardcode them.
• Never commit tokens — add token files to .gitignore; use your CI/CD secret store.
• Use the minimum scope — request only the scopes the integration needs.
• Set short expirations — choose the shortest practical lifetime for PATs.
• Rotate regularly — replace tokens periodically and delete unused ones.
• One token per use — separate tokens per integration or environment so you can revoke narrowly.