Autenticação

A Copera CLI faz seu login uma vez e depois roda todo comando como você. Esta página cobre os tipos de token, os fluxos de login, os perfis e como a CLI decide qual credencial usar quando há várias disponíveis.

Tipos de token

A Copera emite dois tipos de token:

• Personal Access Token (cp_pat_...) — vinculado à sua conta de usuário. Ele cobre toda a superfície da CLI e é obrigatório para comandos de docs, drive, notificações, busca e workspace. Na dúvida, use um PAT.
• Integration API Key (cp_key_...) — vinculado a uma integração, e não a um usuário. Funciona apenas para boards e channels.

dica

Operações de docs e drive sempre exigem um Personal Access Token com as permissões de workspace apropriadas. Se você encontrar um erro de autenticação em copera docs ... ou copera drive ..., confira novamente se está usando um token cp_pat_....

Superfície	cp_pat_ (Personal Access Token)	cp_key_ (Integration API Key)
Boards / tabelas / linhas	Sim	Sim
Channels	Sim	Sim
Docs	Sim	Não
Drive	Sim	Não
Workspace / busca / notificações	Sim	Não

Fluxos de login

A forma mais rápida de autenticar é o fluxo guiado pelo navegador:

copera auth login

A CLI imprime uma URL da Copera, abre-a no seu navegador padrão quando possível e pede que você cole o token gerado de volta no terminal. A URL impressa está sempre disponível, então o mesmo fluxo funciona via SSH, no WSL ou em qualquer terminal onde o navegador talvez não abra automaticamente.

Se você já tem um token, pode salvá-lo diretamente:

Comando	Quando usar
copera auth login	Você quer o fluxo guiado pelo navegador.
copera auth login --token=<value>	Você já tem um token e quer salvá-lo diretamente, sem abrir um navegador.
copera auth login --token	Você já tem um token e quer um prompt de colagem mascarado — sem navegador, e o token nunca cai no histórico do seu shell.

Depois de logado, seu token é armazenado em ~/.copera.toml e reutilizado em todo comando subsequente.

Use um token sem fazer login

Para CI, scripts e agentes de IA, prefira uma variável de ambiente — ela sobrepõe todos os arquivos de configuração e nunca persiste em disco:

export COPERA_CLI_AUTH_TOKEN="cp_pat_xxx"

No Windows PowerShell:

$env:COPERA_CLI_AUTH_TOKEN = "cp_pat_xxx"

Você também pode passar um token por comando com --token, que supera todos os arquivos de configuração, mas tem prioridade menor que a variável de ambiente:

copera boards list --token cp_pat_xxx

Inspecione a sessão atual

copera auth status     # perfil ativo + de onde veio o token
copera auth whoami     # a quem o token pertence

copera auth status é especialmente útil quando algo se comporta de forma inesperada — ele informa se a CLI pegou um token do seu ambiente, de um arquivo de configuração do projeto ou do seu diretório home:

{
  "profile": "default",
  "token_source": "environment variable COPERA_CLI_AUTH_TOKEN",
  "token": "cp_***...***xY2z",
  "configured": true
}

Sair

copera auth logout

Isso remove a credencial armazenada. Rode copera auth login novamente a qualquer momento.

Ordem de resolução do token

Quando você roda um comando, a CLI procura um token nesta ordem — o primeiro que ela encontra vence:

Prioridade	Origem	Exemplo
1	Variável de ambiente	COPERA_CLI_AUTH_TOKEN=cp_pat_xxx
2	Flag --token no comando	copera boards list --token cp_pat_xxx
3	.copera.local.toml no diretório atual	Token local do projeto, ignorado pelo git
4	.copera.toml no diretório atual	Padrões compartilhados do projeto
5	~/.copera.toml	Fallback no nível do usuário

Isso é intencional:

• CI e agentes podem sobrepor todo o resto definindo COPERA_CLI_AUTH_TOKEN.
• Tokens por projeto ficam em .copera.local.toml, que deve ser adicionado ao .gitignore.
• Padrões compartilhados do projeto (como um board_id e table_id padrão, sem token) ficam em .copera.toml, que é seguro versionar.
• Seu token pessoal fica em ~/.copera.toml para todo o resto.

Veja Configuração para o formato completo do arquivo de configuração e como os perfis se encaixam.

Perfis

Um perfil agrupa um token junto com IDs de recursos padrão para que você pare de repetir flags como --board e --table. Perfis ficam nos seus arquivos de configuração em [profiles.<name>]:

[profiles.default]
token    = "cp_pat_abc123..."
board_id = "66abc123def456789012abcd"

[profiles.work]
token    = "cp_key_xyz789..."
board_id = "66ghi789jkl012345678mnop"
table_id = "66pqr012stu345678901vwxy"

Selecione um perfil por comando ou por shell. Se você omitir --profile, a CLI usa default (ou o default_profile definido na sua configuração):

copera boards list --profile work
COPERA_PROFILE=work copera boards list

Sandbox

Para apontar para o ambiente de desenvolvimento da Copera em vez de produção, defina COPERA_SANDBOX=1. Isso troca a URL base da API para https://api-dev.copera.ai/public/v1 e aponta o copera auth login para o app web de desenvolvimento:

COPERA_SANDBOX=1 copera auth login
COPERA_SANDBOX=1 copera boards list

Onde eu consigo um token?

Gere um token a partir do app web da Copera:

1. Abra o workspace que você quer acessar.
2. Vá em Settings → Personal Access Tokens (para cp_pat_...) ou Settings → Integrations (para cp_key_...).
3. Crie um token, copie-o e cole-o no prompt da CLI ou defina-o como COPERA_CLI_AUTH_TOKEN.

Para mais detalhes sobre o que cada tipo de token pode fazer, veja o guia de Autenticação da API.