Copera Public API Authentication: Token Types and Scopes

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

Authorization: Bearer <token>

Copera accepts three general Public API token types. The prefix tells you (and the API) which one you are using. The Omni web widget also has a separate, source-bound server API key for minting short-lived visitor identity tokens.

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
Omni widget server API key	cp_omni_sk_	One web-widget source	Create Omni widget identity tokens only

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 — including Tempo, Agenda, Inbox, automations, meeting notes, and booking-host management — 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. For every other Public API domain, 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.

Omni widget server API key (cp_omni_sk_)

An Omni widget server API key is a backend-only credential bound to one web-widget source. Its only Public API purpose is to call POST /public/v1/omni-channel/identity-tokens and mint a five-minute identity token for a signed-in visitor. It is not a PAT, integration key, widget channelKey, channel ID, or source ID, and it does not use the general access_* scopes below.

Create and manage these keys from the web widget's Configure & install panel under Server API keys. A key is shown only once. Multiple active keys are supported so you can use a separate key per environment and rotate safely.

danger

Keep every cp_omni_sk_… key in your backend secret store. Never send it to a browser or mobile client. Your same-origin backend should authenticate the application user, call Copera with the server key, and return only the short-lived identityToken to the browser.

See the Omni web widget secure verified identity flow for the complete backend and browser flow, and the Create Omni identity token API reference for the endpoint schema.

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, host profiles, booking types, availability schedules, and private links
access_meeting_notes	Meeting notes shared with the token user (read-only)
access_automations	Automation definitions and runs; run, retry, enable, and disable
access_inbox	Inbox threads, mail, drafts, flags, moves, RSVP, and attachments
access_time	Tempo calendars, shelf items, scheduling, and activity blocks
access_agenda	Agenda events, recurrence responses, and ring preferences

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.
• Existing PATs do not acquire newly introduced scopes. Create a new token when you need one of the scopes above.
• Hosted MCP OAuth supports every scope in this table except access_inbox. Inbox is intentionally REST + CLI only.

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.
• Keep Omni server keys backend-only — browsers receive only the five-minute identity token, never the source-bound cp_omni_sk_… key.