AssinAPI
Dashboard

Autenticação

Envie Authorization: Bearer <ASSINAPI_SECRET_KEY> em todas as chamadas.

NUNCA coloque sua Secret Key em:

JavaScript do frontend · navegador · código público · GitHub · frontend do Lovable/Bolt · aplicativo mobile compilado. Use sempre uma camada server-side: Supabase Edge Functions, Cloudflare Workers, Vercel/Netlify Functions, backend Lovable/Supabase, n8n, Make ou seu backend.

Formato das chaves

  • ask_test_… — Sandbox. Só enxerga dados de teste.
  • ask_live_… — Produção. Só enxerga dados reais.
  • asp_… — Personal Access Token (CLI/automações pessoais). Separado das chaves de aplicação.

O secret completo é exibido uma única vez. Guardamos apenas um hash; depois mostramos só o prefixo (ex.: ask_live_8Hkj••••).

ID público × Secret privada

  • Identificador público — o ID (key_…) e o prefixo (ask_live_8Hkj••••). Servem para reconhecer a chave no dashboard, nos logs e no suporte. Não autenticam.
  • Secret Key privada — o valor completo ask_live_…. Autentica chamadas e deve existir apenas no servidor, em ASSINAPI_SECRET_KEY.

Endpoints por ambiente

Sandbox: https://sandbox.api.assinapi.com.br/v1 · Produção: https://api.assinapi.com.br/v1. Usar uma chave no domínio do outro ambiente retorna ENVIRONMENT_MISMATCH.

Credenciais de aplicação × pessoais

Contas de usuário não têm secret próprio. Pessoas autorizadas criam API keys de projeto; registramos quem criou (“João criou a chave X”), mas a chave pertence ao projeto e continua funcionando se João sair da empresa. Para CLI e automações pessoais existe o Personal Access Token (asp_…), separado das chaves de aplicação.

Escopos

documents:read, documents:write, envelopes:read, envelopes:write, envelopes:send, evidence:read, audit:read, webhooks:read, webhooks:write, templates:read, templates:write. Dê a cada integração apenas o necessário.

Rotação sem downtime

  1. Chave A ativa.
  2. Crie a chave B (botão “Rotacionar” ou POST /v1/api-keys/:id/rotate). A e B funcionam ao mesmo tempo.
  3. Atualize a variável de ambiente e faça o deploy.
  4. Revogue A. Eventos API_KEY_CREATED, API_KEY_ROTATED e API_KEY_REVOKED ficam na auditoria.

Chaves pertencem ao projeto

Registramos quem criou cada chave, mas ela não pertence à pessoa: a integração não quebra quando alguém sai da equipe.