Autenticação

Toda requisição se autentica com uma chave de API por site, enviada como token HTTP Bearer.

Authorization: Bearer ck_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Duas classes de chave

Classe	Prefixo	Pode escrever	Onde deve ficar
Secreta	ck_	sim	Só no servidor. Nunca no navegador.
Leitura pública	pk_	não	No HTML de uma página que incorpora o widget.

Uma chave pk_ é somente leitura, vinculada a um site, funciona só a partir das origens que o dono registrou e pode trafegar como ?key=pk_… para que o navegador evite o preflight de CORS. Ela alcança apenas as duas rotas públicas de leitura. Uma chave ck_ é um segredo: as rotas de leitura a aceitam, mas nunca devolvem cabeçalhos CORS para ela, então um navegador não consegue usá-la nem se você tentar, e passá-la como ?key= é um 400 proposital.

Comparação completa, as regras da allowlist de origens e as restrições por chave: Chaves, escopos e restrições.

Formato da chave

Uma chave é um prefixo de classe (ck_ ou pk_) seguido de 32 caracteres base62 (≈ 190 bits de entropia — a mesma entropia nas duas classes; “pública” significa visível, não adivinhável). As chaves são opacas: não as analise nem as divida. A Canverly armazena apenas um hash SHA-256 do segredo e se reserva o direito de mudar a codificação.

Uma chave é vinculada a exatamente um site. O site (site_id) é derivado da chave em toda requisição, então uma chave só consegue ler ou escrever no próprio site: não há como endereçar outro site colocando um id na URL ou no corpo.

De onde vêm as chaves

Gere uma chave no admin em Configurações → Integrações API:

1. Abra o site e vá em Configurações → Integrações API.
2. Clique em Gerar chave, dê a ela um nome reconhecível (por exemplo zapier-blog, ci-publisher) e escolha os escopos de que ela precisa.
3. O segredo ck_… completo é exibido uma única vez, num modal com botão de copiar. Guarde-o no seu gerenciador de segredos imediatamente: ele nunca mais pode ser recuperado.

Depois que o modal é fechado, ficam visíveis só o nome da chave, os escopos e o last_used_at. Se você perder um segredo, revogue-o e crie um novo.

Dica

Use uma chave separada por integração (uma para o Chimpee, uma para o seu job de CI, uma para um agente). Assim você revoga uma única integração sem quebrar as outras, e o last_used_at mostra quais chaves ainda estão ativas. Mantenha leads:read e site:write em chaves próprias, em vez de juntá-los na chave de publicação.

Escopos

Uma chave carrega um ou mais escopos, e os escopos são opt-in: a chave recebe exatamente o que foi pedido na criação e nada por padrão. Peça só o que a integração precisa.

Escopo	Concede
posts:write	Criar e atualizar posts
posts:read	Ler o arquivo publicado (listagem + detalhe)
post_types:read	Descobrir os slugs de post_type válidos
sites:read	Resolver o id, o slug, o domínio e o idioma padrão do site
site:read / site:write	Ler / atualizar as configurações do site
seo:read / seo:write	Ler / atualizar o SEO do post e do site
media:read / media:write	Listar e ler / enviar e excluir arquivos de mídia
analytics:read	Visualizações e números de visitantes do site
leads:read	Envios de formulário — dados pessoais, auditados, limite de requisição próprio
export	Exportação em lote (também exige leads:read / analytics:read para esses recursos)
import	Importação em lote (também exige posts:write)

sites:read e site:read são escopos diferentes, e o singular/plural não é erro de digitação. Veja a tabela completa com as rotas que cada um libera.

Uma requisição a um endpoint cujo escopo a chave não tem retorna 403:

{ "error": { "code": "forbidden", "message": "scope `posts:write` not granted" } }

Restrições por chave

Independentemente dos escopos, o dono pode prender uma chave a uma allowlist de IP, a uma allowlist de países (GeoIP, fail-closed), a uma janela de horário num fuso escolhido e, para chaves pk_, a uma lista de origens permitidas. Elas são verificadas em toda requisição, antes de o bucket do limite de requisição ser cobrado, e uma violação é um 403 que nomeia a dimensão sem nunca revelar a lista:

{ "error": { "code": "forbidden",
  "message": "request blocked by this key's region restriction" } }

Veja Chaves, escopos e restrições.

Envelope de erro

A API devolve um envelope de erro JSON compacto (não é RFC-7807):

{ "error": { "code": "unauthorized", "message": "missing Authorization header" } }

Situação	Status	error.code
Authorization ausente, não-Bearer ou malformado	401	unauthorized
Esquema válido, chave desconhecida ou revogada	401	unauthorized
Uma chave pk_ numa rota que aceita só ck_	401	unauthorized
A chave não tem o escopo exigido	403	forbidden
Requisição bloqueada pela restrição de IP / região / horário da chave	403	forbidden
Uma chave pk_ usada a partir de uma origem não registrada	403	forbidden
Acima do limite de requisição da chave	429	rate_limited

Veja Erros e limites de requisição para a tabela completa.

Revogação e rotação

Revogue uma chave em Configurações → Integrações API (ícone de lixeira). A revogação é imediata: a próxima requisição com essa chave retorna 401. Não há exclusão reversível nem “mostrar de novo”.

Para rotacionar sem indisponibilidade:

1. Gere uma nova chave com os mesmos escopos.
2. Mude a integração para a nova chave.
3. Depois de confirmar que funciona, revogue a chave antiga.

Higiene

• Nunca faça commit de uma chave num repositório nem a coloque em código client-side (a chave é um segredo do servidor). Se uma vazar, revogue-a imediatamente.
• Nenhuma chave de API, de nenhuma classe, consegue criar, listar ou revogar outra chave: o gerenciamento de chaves é feito numa sessão do dono do site no admin. Uma integração não consegue escalar as próprias permissões.
• Trate a ck_… como uma senha: guarde-a num gerenciador de segredos / variável de ambiente.
• Prefira uma chave por consumidor, para que o raio de impacto de um vazamento seja uma única integração.