Autenticazione della Copera Public API: tipi di token e scope

Ogni richiesta alla Public API deve includere un token nell'header Authorization con lo schema Bearer:

Authorization: Bearer <token>

Copera accetta tre tipi generali di token Public API. Il prefisso ti dice (e all'API) quale stai usando. Il widget web Omni ha anche una server API key separata, legata alla source, per emettere token di identità visitatore a breve durata.

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_)

Un Personal Access Token autentica l'API come te. Le richieste sono attribuite al tuo account utente ed ereditano il tuo accesso nel workspace, limitate dagli scope che concedi al token. I PAT sbloccano l'intera superficie API — boards, export, docs, drive, search, channels, notifications, workspace e bookings — e sono la scelta consigliata per script, pipeline CI e automazioni personali.

Come ottenerne uno

1. Apri Workspace Settings → Integrations.
2. Seleziona la tab Personal Tokens.
3. Clicca Create new token.
4. Imposta un nome, scegli gli scope di cui ha bisogno e una data di scadenza (fino a 1 anno).
5. Copia il token immediatamente — viene mostrato una sola volta.

Caratteristiche

• Workspace-scoped — ogni token è legato a un workspace.
• Agisce come la tua identità — le chiamate sono attribuite a te e rispettano i tuoi permessi.
• Scade — fino a un massimo di 1 anno; i token scaduti restituiscono 401.
• Scoped — solo gli scope che concedi vengono onorati.

Esempio

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

Integration API Key (cp_key_)

Un'Integration API Key autentica come un'integrazione (un bot) anziché come un utente specifico. È la scelta giusta quando vuoi un'identità separata che opera indipendentemente da qualsiasi utente — ad esempio un bot che pubblica su channel o legge dati di board.

nota

Le Integration API Key coprono solo boards e channels. Per chiamare endpoint docs, drive, search, notifications, workspace o bookings, usa invece un Personal Access Token.

Caratteristiche

• Identità bot — le richieste sono attribuite all'integrazione, non a un utente.
• Superficie boards + channels — progettata per gli endpoint di board e channel.
• Richiede accesso esplicito — l'integrazione deve ricevere gli scope rilevanti ed essere aggiunta come participant dei channel o delle board specifici che deve raggiungere.

Crea un'integrazione e genera la sua key da Workspace Settings → Integrations.

Token MCP OAuth (cp_oat_)

I token MCP OAuth vengono emessi automaticamente quando un client IA si connette al workspace tramite l'MCP server. Non li crei a mano — il flusso OAuth li emette per conto dell'utente. Autenticano come l'utente che si connette, con scope a ciò che l'integrazione MCP può fare.

Se stai costruendo un'integrazione diretta, usa un PAT o un'Integration API Key. I token cp_oat_ fanno parte del flusso di connessione MCP.

Server API key del widget Omni (cp_omni_sk_)

Una server API key del widget Omni è una credenziale solo-backend legata a una source di web-widget. Il suo unico scopo nella Public API è chiamare POST /public/v1/omni-channel/identity-tokens ed emettere un identity token di cinque minuti per un visitatore autenticato. Non è un PAT, un'integration key, un channelKey del widget, un channel ID o un source ID, e non usa gli scope generali access_* sotto.

Crea e gestisci queste key dal pannello Configure & install del web widget sotto Server API keys. Una key viene mostrata una sola volta. Sono supportate più key attive così puoi usare una key separata per ambiente e ruotare in sicurezza.

pericolo

Tieni ogni key cp_omni_sk_… nello store di secret del backend. Non inviarla mai a un browser o a un client mobile. Il tuo backend same-origin deve autenticare l'utente dell'applicazione, chiamare Copera con la server key e restituire al browser solo l'identityToken a breve durata.

Vedi il flusso di identità verificata sicura del widget web Omni per il flusso completo backend e browser, e il riferimento API Create Omni identity token per lo schema dell'endpoint.

Scope

Gli scope controllano quali domini un token può raggiungere. Concedi solo ciò di cui l'integrazione ha bisogno.

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

Note sulla copertura degli scope:

• Gli endpoint Workspace (info, members, teams) richiedono un PAT valido per un utente interno (non external) — non c'è uno scope workspace separato.
• Search non ha un unico scope. Una richiesta di search restituisce solo i tipi di entità che il token è autorizzato a leggere: i documenti richiedono access_docs, channel e messaggi richiedono access_channels, gli item del drive richiedono access_drive. Altri tipi (come todo e chat IA) sono ricercabili con qualsiasi token valido.
• Export gira sulle table di board, quindi richiede access_boards.

Una richiesta a un dominio per cui al token manca lo scope restituisce 403 Forbidden. Vedi Gestione errori.

Best practice di sicurezza

• Conserva i token in modo sicuro — usa variabili d'ambiente o un secret manager. Non hardcodarli mai.
• Non committare mai i token — aggiungi i file di token a .gitignore; usa lo store di secret del CI/CD.
• Usa lo scope minimo — richiedi solo gli scope di cui l'integrazione ha bisogno.
• Imposta scadenze brevi — scegli la lifetime più breve pratica per i PAT.
• Ruota regolarmente — sostituisci i token periodicamente ed elimina quelli non usati.
• Un token per uso — token separati per integrazione o ambiente così puoi revocare in modo mirato.
• Tieni le server key Omni solo-backend — i browser ricevono solo l'identity token di cinque minuti, mai la key cp_omni_sk_… legata alla source.