Autenticacao

Toda requisicao a Public API deve incluir um token no header Authorization usando o esquema Bearer:

Authorization: Bearer <token>

A Copera aceita tres tipos de token. O prefixo indica (a voce e a API) qual deles voce esta usando.

Tipo de token	Prefixo	Identidade	Superficie
Personal Access Token	cp_pat_	Voce (o usuario que o criou)	API completa
Integration API Key	cp_key_	A integracao (um bot)	Apenas Boards + Channels
MCP OAuth token	cp_oat_	O usuario conectado	Emitido pelo servidor MCP

Personal Access Token (cp_pat_)

Um Personal Access Token autentica a API como voce. As requisicoes sao atribuidas a sua conta de usuario e herdam seu acesso dentro do workspace, limitadas pelos escopos que voce concede ao token. PATs desbloqueiam a superficie completa da API — boards, export, docs, drive, busca, channels, notificacoes, workspace e bookings — e sao a escolha recomendada para scripts, pipelines de CI e automacao pessoal.

Como obter um

1. Abra Workspace Settings → Integrations.
2. Selecione a aba Personal Tokens.
3. Clique em Create new token.
4. Defina um nome, escolha os escopos de que ele precisa e defina uma data de expiracao (ate 1 ano).
5. Copie o token imediatamente — ele e exibido apenas uma vez.

Caracteristicas

• Limitado ao workspace — cada token esta vinculado a um unico workspace.
• Atua como sua identidade — as chamadas sao atribuidas a voce e respeitam suas permissoes.
• Expira — ate no maximo 1 ano; tokens expirados retornam 401.
• Com escopo — apenas os escopos que voce concede sao honrados.

Exemplo

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

Integration API Key (cp_key_)

Uma Integration API Key autentica como uma integracao (um bot) em vez de um usuario especifico. E a escolha certa quando voce quer uma identidade separada que opere de forma independente de qualquer usuario — por exemplo, um bot que publica em channels ou le dados de boards.

observação

As Integration API Keys cobrem apenas boards e channels. Para chamar endpoints de docs, drive, busca, notificacoes, workspace ou bookings, use um Personal Access Token.

Caracteristicas

• Identidade de bot — as requisicoes sao atribuidas a integracao, nao a um usuario.
• Superficie de boards + channels — projetada para endpoints de boards e channels.
• Requer acesso explicito — a integracao precisa receber os escopos relevantes e ser adicionada como participante dos channels ou boards especificos que precisa acessar.

Crie uma integracao e gere sua chave em Workspace Settings → Integrations.

MCP OAuth token (cp_oat_)

Os MCP OAuth tokens sao emitidos automaticamente quando um cliente de IA se conecta ao seu workspace pelo servidor MCP. Voce nao cria esses tokens manualmente — o fluxo OAuth os gera em nome do usuario. Eles autenticam como o usuario que esta se conectando, limitados ao que a integracao MCP pode fazer.

Se voce esta criando uma integracao direta, use um PAT ou uma Integration API Key. Os tokens cp_oat_ fazem parte do fluxo de conexao do MCP.

Escopos

Os escopos controlam quais dominios um token pode acessar. Conceda apenas o que sua integracao precisa.

Escopo	Concede acesso a
access_boards	Boards, tabelas, linhas, comentarios de linhas, markdown de linhas, export de tabelas
access_channels	Channels, mensagens de channels, mensagens diretas
access_docs	Documentos — ler, gravar, buscar, arvore
access_drive	Drive — navegar, buscar, baixar, fazer upload, pastas
access_notifications	Notificacoes — listar, atualizar, excluir
access_bookings	Bookings e tipos de booking

Observacoes sobre a cobertura dos escopos:

• Os endpoints de Workspace (info, members, teams) exigem um PAT valido de um usuario interno (nao externo) — nao ha um escopo de workspace separado.
• A Busca nao tem um escopo unico. Uma requisicao de busca retorna apenas os tipos de entidade que seu token pode ler: documentos precisam de access_docs, channels e mensagens precisam de access_channels, itens do drive precisam de access_drive. Outros tipos (como todos e chats de IA) podem ser buscados com qualquer token valido.
• O Export roda sobre tabelas de boards, entao requer access_boards.

Uma requisicao a um dominio para o qual seu token nao tem o escopo retorna 403 Forbidden. Veja Tratamento de Erros.

Boas praticas de seguranca

• Armazene tokens com seguranca — use variaveis de ambiente ou um gerenciador de segredos. Nunca os deixe fixos no codigo.
• Nunca faca commit de tokens — adicione arquivos de token ao .gitignore; use o cofre de segredos do seu CI/CD.
• Use o escopo minimo — solicite apenas os escopos de que a integracao precisa.
• Defina expiracoes curtas — escolha o tempo de vida mais curto e pratico para os PATs.
• Rotacione com regularidade — substitua os tokens periodicamente e exclua os que nao sao usados.
• Um token por uso — separe tokens por integracao ou ambiente para revoga-los de forma pontual.