Autenticação

Toda requisição à Public API deve incluir um token no header Authorization usando o esquema Bearer:

Authorization: Bearer <token>

A Copera aceita três tipos gerais de token da Public API. O prefixo indica (a você e à API) qual deles você está usando. O widget web do Omni também tem uma chave de API do servidor separada, vinculada à fonte, para emitir tokens de identidade de curta duração para visitantes.

Tipo de token	Prefixo	Identidade	Superfície
Personal Access Token	cp_pat_	Você (o usuário que o criou)	API completa
Integration API Key	cp_key_	A integração (um bot)	Apenas Boards + Channels
MCP OAuth token	cp_oat_	O usuário conectado	Emitido pelo servidor MCP
Chave de API do servidor do widget Omni	cp_omni_sk_	Uma fonte de widget web	Apenas para criar tokens de identidade do widget Omni

Personal Access Token (cp_pat_)

Um Personal Access Token autentica a API como você. As requisições são atribuídas à sua conta de usuário e herdam seu acesso dentro do workspace, limitadas pelos escopos que você concede ao token. PATs desbloqueiam a superfície completa da API — boards, export, docs, drive, busca, channels, notificações, workspace e bookings — e são a escolha recomendada para scripts, pipelines de CI e automação 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 expiração (até 1 ano).
5. Copie o token imediatamente — ele é exibido apenas uma vez.

Características

• Limitado ao workspace — cada token está vinculado a um único workspace.
• Atua como sua identidade — as chamadas são atribuídas a você e respeitam suas permissões.
• Expira — o prazo máximo é de um ano; tokens expirados retornam 401.
• Com escopo — apenas os escopos que você concede são respeitados.

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 a API como uma integração (um bot) em vez de um usuário específico. É a escolha certa quando você quer uma identidade separada que opere de forma independente de qualquer usuário — por exemplo, um bot que publica em channels ou lê dados de boards.

observação

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

Características

• Identidade de bot — as requisições são atribuídas à integração, não a um usuário.
• Superfície de boards + channels — projetada para endpoints de boards e channels.
• Requer acesso explícito — a integração precisa receber os escopos relevantes e ser adicionada como participante dos channels ou boards específicos que precisa acessar.

Crie uma integração e gere sua chave em Workspace Settings → Integrations.

MCP OAuth token (cp_oat_)

Os MCP OAuth tokens são emitidos automaticamente quando um cliente de IA se conecta ao seu workspace pelo servidor MCP. Você não cria esses tokens manualmente — o fluxo OAuth os gera em nome do usuário. Eles autenticam como o usuário que está se conectando, limitados ao que a integração MCP pode fazer.

Se você está criando uma integração direta, use um PAT ou uma Integration API Key. Os tokens cp_oat_ fazem parte do fluxo de conexão do MCP.

Chave de API do servidor do widget Omni (cp_omni_sk_)

Uma chave de API do servidor do widget Omni é uma credencial exclusiva do backend, vinculada a uma fonte de widget web. Sua única finalidade na Public API é chamar POST /public/v1/omni-channel/identity-tokens e emitir um token de identidade de cinco minutos para um visitante autenticado. Ela não é um PAT, uma chave de integração, um channelKey do widget, um ID de channel nem um ID da fonte e não usa os escopos gerais access_* abaixo.

Crie e gerencie essas chaves no painel Configurar e instalar do widget web, em Chaves de API do servidor. Uma chave é exibida apenas uma vez. É possível manter várias chaves ativas, usar uma chave separada por ambiente e fazer a rotação com segurança.

perigo

Mantenha todas as chaves cp_omni_sk_… no armazenamento de segredos do seu backend. Nunca as envie a um navegador ou aplicativo móvel. Seu backend de mesma origem deve autenticar o usuário do aplicativo, chamar a Copera com a chave do servidor e retornar somente o identityToken de curta duração ao navegador.

Consulte o fluxo seguro de identidade verificada do widget web do Omni para conhecer o fluxo completo no backend e no navegador e a referência da API para criar um token de identidade do Omni para ver o schema do endpoint.

Escopos

Os escopos controlam quais domínios um token pode acessar. Conceda apenas o que sua integração precisa.

Escopo	Concede acesso a
access_boards	Boards, tabelas, linhas, comentários de linhas, markdown de linhas, export de tabelas
access_channels	Channels, mensagens de channels, mensagens diretas
access_docs	Documentos — ler, gravar, buscar, árvore
access_drive	Drive — navegar, buscar, baixar, fazer upload, pastas
access_notifications	Notificações — listar, atualizar, excluir
access_bookings	Bookings e tipos de booking

Observações sobre a cobertura dos escopos:

• Os endpoints de Workspace (info, members, teams) exigem um PAT válido de um usuário interno (não externo) — não há um escopo de workspace separado.
• A Busca não tem um escopo único. Uma requisição 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 válido.
• O Export roda sobre tabelas de boards, então requer access_boards.

Uma requisição a um domínio para o qual seu token não tem o escopo retorna 403 Forbidden. Veja Tratamento de Erros.

Boas práticas de segurança

• Armazene tokens com segurança — use variáveis de ambiente ou um gerenciador de segredos. Nunca os deixe fixos no código.
• Nunca faça commit de tokens — adicione arquivos de token ao .gitignore; use o cofre de segredos do seu CI/CD.
• Use o escopo mínimo — solicite apenas os escopos de que a integração precisa.
• Defina expirações curtas — escolha o tempo de vida mais curto e prático para os PATs.
• Rotacione com regularidade — substitua os tokens periodicamente e exclua os que não são usados.
• Um token por finalidade — separe tokens por integração ou ambiente para revogá-los de forma pontual.
• Mantenha as chaves do servidor Omni somente no backend — os navegadores recebem apenas o token de identidade de cinco minutos, nunca a chave cp_omni_sk_… vinculada à fonte.