Autenticação

A API autentica servidores com chaves de API da organização. Uma chave pertence a uma organização (não a uma pessoa), tem um conjunto de permissões e funciona em exatamente um modo: teste ou produção.

Enviando a chave

Use qualquer um dos cabeçalhos:

# Authorization header (recommended)
curl https://api.bonafidesign.com/v1/envelopes -H "Authorization: Bearer bf_live_…"

# or x-api-key
curl https://api.bonafidesign.com/v1/envelopes -H "x-api-key: bf_live_…"

As chaves têm o formato bf_live_… ou bf_test_…. A ausência de chave resulta em 401 (unauthorized); uma chave malformada, revogada ou expirada também resulta em 401. Mantenha as chaves no seu servidor: nunca as inclua em um navegador ou app para celular. Para assinar no navegador, gere uma sessão de assinatura.

Chaves de teste e de produção

	Teste (`bf_test_…`)	Produção (`bf_live_…`)
Documentos	Renderizados com a marca d’água `TEST`	Sem marca d’água
E-mail	Entregue apenas a membros da sua organização	Entregue a todos os destinatários
Cobrança	Gratuito e ilimitado, nunca contabilizado	Os envelopes concluídos contam para o seu plano
Dados	Envelopes, links e endpoints de webhook criados com a chave ficam no modo de teste	Modo de produção

O modo vem da chave, nunca da requisição: ?test_mode=true em POST /v1/envelopes só vale para sessões do painel. As listagens (GET /v1/envelopes, GET /v1/signing-links) só retornam o modo da chave, e os eventos de um envelope só vão para endpoints de webhook do mesmo modo. Todo envelope e todo payload de webhook informam em que modo estão (testMode).

Criando e revogando chaves

As chaves são gerenciadas no painel, em Configurações › Chaves de API, por membros com a permissão apikey:manage (proprietários e administradores). O segredo é exibido uma única vez, quando a chave é criada. Você pode dar à chave um nome, um modo, uma validade (de 1 a 365 dias, ou nenhuma) e escopos.

Escopos

Os escopos de uma chave são as permissões da organização que ela pode usar. Por padrão, uma chave nova recebe as permissões de quem a criou, exceto as administrativas (org:manage, member:manage, sso:manage, apikey:manage, billing:manage), e ninguém pode conceder a uma chave uma permissão que não tem. Uma chamada fora dos escopos da chave resulta em 403, indicando a permissão que falta:

{
  "type": "https://bonafidesign.com/problems/forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing permission: envelope:send.",
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Permissão	Permite que a chave
`template:read`	Liste e leia modelos, versões e os respectivos PDFs
`template:write`	Crie modelos, envie arquivos, salve rascunhos e exclua modelos não usados
`template:publish`	Publique um rascunho como nova versão
`envelope:read`	Liste e leia envelopes, documentos e trilhas de auditoria; liste links de assinatura
`envelope:send`	Crie envelopes, sessões de assinatura e links de assinatura; reenvie links
`envelope:void`	Anule envelopes em andamento
`org:manage`	Gerencie endpoints de webhook e reenvie eventos; leia as configurações da organização
`billing:manage`	Leia o uso (`GET /v1/usage`) e os valores das faturas

Gerenciar endpoints de webhook exige org:manage, que as chaves não recebem por padrão: cadastre os endpoints no painel ou crie explicitamente uma chave com esse escopo.

O que cada endpoint aceita

Cada operação na referência da API lista os esquemas de segurança dela. Em resumo:

Chave de API ou sessão do painel: modelos, envelopes, sessões de assinatura, links de assinatura, endpoints de webhook, configurações da organização, visão geral de cobrança e uso.
Somente sessão do painel: chaves de API, tokens SCIM, configurações da conexão SSO, envio do logotipo da organização, checkout e portal de cobrança, exibição de um segredo de webhook.
Token do signatário: /v1/signing/*, usado pela página hospedada e pelo <bf-signing> com um token de sessão (bfs_…) ou com o token de acesso pelo qual ele é trocado (bfa_…).
Público: /v1/links/{id} (links permanentes), /v1/sso/discover e a API de verificação (/v1/public/*, /.well-known/bona-fide/keys.json).

Entrando no painel

Pessoas (não servidores) entram no painel em https://app.bonafidesign.com/sign-in. O padrão é e-mail e senha; as alternativas são um código de seis dígitos enviado por e-mail (Enviar um código por e-mail), um link mágico, uma chave de acesso, Google ou Microsoft e o SSO da sua empresa.

Criar uma conta com senha envia um e-mail: um código que confirma que o endereço é seu. Até lá, a senha não permite entrar. Cadastrar-se com um endereço que já tem conta não altera nada e recebe exatamente a mesma resposta de um cadastro novo; o dono do endereço recebe um e-mail explicando como entrar.
As senhas têm de 12 a 128 caracteres e são armazenadas como hashes scrypt com salt. Uma senha nova que aparece em um vazamento de dados conhecido é recusada: só os cinco primeiros caracteres do hash SHA-1 dela são enviados ao Have I Been Pwned (k-anonimato), nunca a senha. Se esse serviço não responder em dois segundos, a senha é aceita sem a verificação.
Esqueceu a senha? O e-mail de redefinição leva a uma página onde você escolhe uma nova. O link funciona uma única vez e expira depois de uma hora, e usá-lo encerra sua sessão em todos os dispositivos.
Ainda não tem senha? Contas criadas com código, link, chave de acesso ou Google / Microsoft continuam entrando desse jeito e podem adicionar uma senha em Configurações › Conta. Definir a primeira senha exige ter entrado nos últimos 15 minutos (a página envia um código por e-mail para confirmar que é você); alterá-la exige a senha atual. Nos dois casos, suas outras sessões são encerradas.
Os erros nunca revelam contas: uma senha errada, um endereço desconhecido e uma conta sem senha recebem a mesma resposta, e um pedido de redefinição sempre informa que o e-mail está a caminho.
Limites de taxa: entrada com senha, cadastro e pedidos de redefinição são limitados por endereço IP e por endereço de e-mail; acima do limite, a resposta é 429 até a janela passar.
SSO da empresa: quando sua organização exige SSO, os membros dos domínios de e-mail dela entram apenas pelo provedor de identidade. Senhas, códigos e links mágicos são recusados para eles; os proprietários mantêm o código por e-mail como acesso de emergência.

IDs de requisição

Toda resposta traz um cabeçalho x-request-id, e todo corpo de erro, um requestId. Você pode enviar seu próprio x-request-id (de 8 a 128 caracteres entre A-Z a-z 0-9 . _ -) para correlacionar logs; caso contrário, a API gera um. Informe esse ID ao entrar em contato com o suporte.