Provisionamento de Credenciais
Quick Reference
Tipos de Credenciais
| Credencial | Formato | Finalidade |
|---|---|---|
entity_uuid | UUID v4 | Identifica sua entidade comercial na A55 |
merchant_uuid | UUID v4 | Identifica uma configuração específica de comerciante |
client_id | String | Identificador de cliente OAuth2 para autenticação |
client_secret | String | Segredo de cliente OAuth2 — mantenha em sigilo |
wallet_uuid | UUID v4 | Identifica uma carteira que contém cobranças |
Hierarquia
Entity (entity_uuid)
└── Merchant (merchant_uuid)
├── Wallet A (wallet_uuid)
│ ├── Charge 1
│ └── Charge 2
└── Wallet B (wallet_uuid)
└── Charge 3
Uma única entidade pode ter múltiplos comerciantes (por exemplo, diferentes linhas de negócio), e cada comerciante pode ter múltiplas carteiras.
Sandbox vs Produção
| Aspecto | Sandbox | Produção |
|---|---|---|
| URL base da API | https://sandbox.api.a55.tech | https://api.a55.tech |
| URL de autenticação | https://auth.sandbox.a55.tech | https://auth.a55.tech |
| Pool Cognito | Pool separado | Pool separado |
| Credenciais | client_id/client_secret diferentes | client_id/client_secret diferentes |
| Dinheiro real | Não | Sim |
| Cartões de teste | Aceitos | Rejeitados |
As credenciais não são intercambiáveis
Credenciais do sandbox não funcionam em produção e vice-versa. Cada ambiente possui seu próprio pool Cognito com client IDs e secrets separados.
Como Rotacionar Credenciais
- Entre em contato com tech.services@a55.tech solicitando uma rotação de credenciais
- A A55 gera um novo
client_secretmantendo seuclient_idinalterado - Ambos os secrets (antigo e novo) permanecem válidos por um período de transição de 24 horas
- Atualize suas variáveis de ambiente e faça o deploy
- Confirme que o novo secret funciona e notifique a A55 para revogar o antigo
# After receiving new credentials
export A55_CLIENT_SECRET="new_rotated_secret_value"
# Verify authentication works
curl -s -X POST "https://auth.sandbox.a55.tech/oauth2/token" \
-d "grant_type=client_credentials" \
-d "client_id=${A55_CLIENT_ID}" \
-d "client_secret=${A55_CLIENT_SECRET}" \
-d "scope=api/readwrite" | python3 -m json.tool
Boas Práticas de Segurança
Nunca faça commit de secrets no controle de versão
# .gitignore
.env
.env.local
.env.production
Use variáveis de ambiente
# .env (local development only — never commit this file)
A55_CLIENT_ID=your_client_id
A55_CLIENT_SECRET=your_client_secret
# In your application
import os
client_id = os.environ["A55_CLIENT_ID"]
Rotacione a cada 90 dias
Crie um lembrete no calendário. A rotação de credenciais limita o raio de impacto de um secret vazado.
Limite o acesso
- Apenas serviços backend devem ter acesso ao
client_secret - Nunca exponha credenciais em código frontend, logs ou mensagens de erro
- Use o gerenciador de secrets do seu provedor de nuvem (AWS Secrets Manager, Azure Key Vault, GCP Secret Manager)
Monitore o uso
- Rastreie a emissão de tokens nos seus logs
- Configure alertas para falhas de autenticação — elas podem indicar credenciais vazadas ou revogadas
- Revise os padrões de acesso à API mensalmente
A A55 utiliza o tipo de concessão OAuth2 client_credentials, projetado para autenticação máquina-a-máquina (M2M):
- Seu servidor envia
client_id+client_secretpara o endpoint de token - O Cognito da A55 retorna um token de acesso JWT válido por 3600 segundos (1 hora)
- Você inclui este token como
Authorization: Bearer <token>em cada requisição à API - Antes que o token expire, seu código deve solicitar um novo
Não há interação do usuário, nenhum código de autorização, nenhum redirecionamento — trata-se de uma troca direta de credenciais adequada para serviços backend.
Estrutura do token: O JWT contém seu entity_uuid, escopos concedidos e expiração. Você pode decodificá-lo (é base64), mas não precisa — passe-o como está para a API.