Autenticacao

API Key via header HTTP

4 min de leitura

Todas as requisições precisam do header x-api-key com a chave do tenant. Requisições sem header válido retornam 401 Unauthorized antes de qualquer processamento.

Nunca exponha sua API key no frontend. Faça todas as chamadas pelo backend. Chaves comprometidas podem ser revogadas no painel sem downtime.
x-api-key: Oz_live_a1b2c3d4e5f6g7h8i9j0

Prefixos: Oz_live_ vs Oz_test_

O prefixo da chave indica o ambiente ao qual ela pertence. Nunca use uma chave de produção em testes — isso gera transações reais e cobranças reais.

PrefixoAmbienteGateways disponíveisGera cobranças?
Oz_live_ Produção Stripe, MercadoPago, PayPal Sim
Oz_test_ Teste / Staging MOCK, sandboxes dos gateways Não
orquestraio-livre-123 Desenvolvimento local Somente MOCK Não

A chave de desenvolvimento orquestraio-livre-123 está incluída no data.sql e é carregada automaticamente pelo Docker. Use-a para testes locais com o gateway MOCK.

Gerar e Revogar Chaves

API keys são gerenciadas pelo painel de administração do Orquestraio ou diretamente no banco via data.sql em ambiente de desenvolvimento.

Gerar nova chave

Acesse o painel → Configurações → API Keys → Nova Chave. O valor completo é exibido uma única vez — copie e armazene com segurança. O Orquestraio guarda apenas o hash.

Revogar chave

Acesse o painel → Configurações → API Keys → Revogar. A revogação é instantânea — todas as requisições usando aquela chave passam a retornar 401 imediatamente. Nenhum downtime.

Rotação recomendada: Troque chaves de produção a cada 90 dias ou imediatamente após qualquer suspeita de comprometimento.

Estados da Chave e Respostas

Entender a diferença entre 401 e 403 ajuda a diagnosticar problemas rapidamente:

EstadoHTTPCausaAção
Header ausente 401 Nenhum header x-api-key enviado Adicione o header em todas as requisições
Chave inválida 401 Hash SHA-256 não encontrado no banco Verifique se a chave está correta
Tenant inativo 403 Tenant com status INACTIVE Entre em contato com o suporte
Chave revogada 401 Chave removida do banco Gere uma nova chave e atualize suas configurações
Boas práticas de armazenamento: Armazene a API key em variável de ambiente (ORQUESTRAIO_API_KEY), nunca no código-fonte ou em arquivos commitados. Em produção, use um secret manager (AWS Secrets Manager, HashiCorp Vault, etc.).