Autenticação e escopos
A chave
Toda chamada à API leva a chave no header:
Authorization: Bearer pico_sk_…Ela é criada em Conta → API e MCP, aparece uma vez e nunca mais pode ser lida — o Pico guarda só um hash. Perdeu? Crie outra e revogue a antiga. A lista mostra o começo (pico_sk_ab12cd…), o último uso e a validade.
A chave nasce presa a um workspace (o seu tenant) e a você. Tudo que ela lê ou escreve é desse workspace; nada de tenantId no corpo ou na query — o servidor decide por quem é a chave.
Os quatro escopos
| Escopo | Deixa | Nasce marcado? |
|---|---|---|
leitura | ler perfil, pesquisas, peças, leads, inbox, custo | sim |
escrita | salvar perfil, editar rascunhos, agendar, ajustar o teto, traduzir | sim |
gasto | pedir pesquisas e gerar peças/análises com IA — gasta dinheiro da sua conta (Virlo) | não |
publicacao | publicar peças e responder leads — age na sua conta do Instagram/TikTok | não |
Cada rota exige um escopo (está no cabeçalho de cada uma na referência). Chave sem o escopo recebe 403 escopo_insuficiente. Escopos não mudam depois de criados: crie outra chave.
Regra prática: uma chave leitura+escrita para o dia a dia; uma com gasto só quando for pesquisar, com o teto do mês ajustado; publicacao só se você quer que o Claude Code (ou o seu script) publique — ele ainda vai pedir sua confirmação a cada vez.
O que a chave NÃO faz
- Não cria, lista nem revoga chaves.
/v1/chavesaceita só a sessão do app (o cookie do navegador). Uma chave vazada não fabrica outra com mais poder. - Não muda de workspace. Modo agência:
clientIdnas rotas que aceitam é conferido contra os clientes que você opera. - Não vive no seu repositório. No
.mcp.jsonuse${PICO_API_KEY}(o Claude Code expande variável de ambiente); no CI, um segredo. Se cair no git, revogue.
Validade e revogação
- Ao criar: sem prazo, 30 ou 90 dias. Expirada, responde
401como se não existisse. - Revogar é imediato e irreversível. As ferramentas que usam a chave param na hora.
- Sair do workspace (modo agência) desliga as chaves daquela pessoa naquele workspace.
Sessão vs. chave
As rotas da v1 aceitam também a sessão do app (o cookie), com todos os escopos — é assim que a própria tela usa a API. Uma request com chave e cookie é tratada como chave (os escopos são os dela). Para integrações de fora, use chave: sessão exige mesma origem.
Erros de autenticação
| Status | code | O que é |
|---|---|---|
| 401 | chave_invalida | não existe, revogada, expirada ou operador fora do workspace — resposta igual nos quatro casos |
| 401 | sem_sessao | rota chamada sem chave e sem cookie |
| 403 | so_sessao | /v1/chaves com chave de API |
| 403 | escopo_insuficiente | a chave não tem o escopo da rota |
| 403 | cross_site | sessão vinda de outro site por script |
A resposta 401 traz WWW-Authenticate: Bearer realm="pico".