Autenticação

A BlendFi usa autenticação Bearer-token simples. Todo request em /v1/* envia sua API key no header Authorization. Não há login, sessão ou refresh de token, a chave é a sessão.

O contrato

GET /v1/users HTTP/1.1
Host: api.sandbox.blendfi.com.br
Authorization: Bearer sk_test_xxx

Três regras:

1. Prefixo Bearer obrigatório. Apenas Authorization: sk_test_… retorna 401 authentication_required. Atenção ao espaço.
2. Chave enviada em todo request. Sem padrão troca-por-cookie-de-sessão. A chave é texto plano em todo trajeto, por isso o TLS é obrigatório.
3. Apenas HTTPS. HTTP puro é rejeitado na borda.

Formatos de chave

Uso entre ambientes é rejeitado:

• sk_test_… contra a URL base de produção → 401 api_key_env_mismatch
• sk_live_… contra a URL base de sandbox → 401 api_key_env_mismatch

Isso é intencional: evita movimentar dinheiro real por acidente durante testes e evita que chamadas de teste poluam produção.

Rotação de chave

Integrações em nível de produção rotacionam chaves em uma cadência (a cada 90 dias é o ritmo comum) ou em resposta a um comprometimento.

A rotação é por autoatendimento via API. Uma única chamada, POST /v1/api-keys/{id}/rotate, emite uma chave nova com as mesmas capabilities e o mesmo nome, retorna o novo segredo exatamente uma vez e revoga a chave antiga imediatamente. O fluxo recomendado:

1. GET /v1/api-keys para encontrar o id da chave que você quer rotacionar.
2. POST /v1/api-keys/{id}/rotate; capture o novo segredo na resposta (ele é mostrado uma única vez e não pode ser recuperado depois).
3. Implante o novo segredo na sua aplicação (deploy ou hot-reload do segredo).

A rotação é uma transição imediata: a chave antiga para de autenticar no instante em que você rotaciona, então requisições que ainda a usam retornam authentication_failed. Tenha o novo segredo pronto para implantar na mesma mudança, para que não haja lacuna.

Erros

Descrições completas no catálogo de erros.

Leia em seguida

• Sandbox e chaves, ambientes e o fluxo de pedido de chave
• Conceitos → Erros e retentativas, formato da resposta de erro
• Início rápido, faça sua primeira chamada