CyrusDocs

API Keys

Crie, liste e revogue suas API Keys no painel Cyrus.

Gerenciar via painel

Acesse o painel em Configurações → API Keys.

A partir dali você pode:

  • Gerar novas chaves com um nome descritivo e escolher o ambiente (sandbox ou production)
  • Visualizar o preview de cada chave (sk_...xxxx — últimos 4 caracteres)
  • Revogar chaves individualmente
⚠

A chave completa é exibida somente uma vez, no momento da criação. Copie e armazene imediatamente em local seguro. Após fechar a modal, não é possível recuperá-la.

Estrutura de uma API Key

sk_live_4a8f2c1d9e3b7a5f6c2d8e4b1a9f3c7d2e5b8a1f4c9e2b6d0a3f7c1e4b8d2a
^^^^^^^                                                                    prefixo do ambiente
        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^  token aleatório (256 bits)

Prefixos

| Prefixo | Ambiente | Uso | |---|---|---| | sk_live_ | Produção | Transações reais com dinheiro real | | sk_test_ | Sandbox / Teste | Desenvolvimento e testes, sem efeito financeiro |

Usando a chave nas requisições

Inclua a chave no header x-api-key de cada requisição:

curl https://api.cyrus.com.br/api/v1/charges 
  -H "x-api-key: sk_live_sua_chave_aqui" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 100.00 }'

Exemplo com variável de ambiente

# .env
CYRUS_API_KEY=sk_live_sua_chave_aqui
const response = await fetch('https://api.cyrus.com.br/api/v1/charges', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.CYRUS_API_KEY!,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 100.00 }),
})

Segurança

O que fazer

  • Armazene chaves em gerenciadores de segredos (AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, Doppler)
  • Use variáveis de ambiente em aplicações containerizadas
  • Rotacione chaves periodicamente e após mudanças de equipe
  • Use uma chave por integração para facilitar revogação sem afetar outras integrações

O que não fazer

  • Não inclua chaves em código-fonte commitado
  • Não exponha chaves em logs de aplicação
  • Não envie chaves em URLs (query strings são registradas em logs de servidor)
  • Não use sk_live_ em ambiente de desenvolvimento ou CI/CD

Revogação

Para revogar uma chave sem downtime:

  1. Gere uma nova chave no painel (mesmo nome, mesmo ambiente)
  2. Atualize a variável de ambiente na sua aplicação
  3. Verifique que as requisições estão usando a nova chave
  4. Revogue a chave antiga no painel

O processo pode ser feito sem interromper o serviço. Após a revogação, a chave retorna 401 Unauthorized imediatamente.