Pular para o conteúdo principal
A Safefy utiliza OAuth2 Client Credentials para autenticação. Você precisa obter um token JWT antes de fazer qualquer outra requisição.

​
Como funciona

​
Limite de geração de token (importante)

Para proteger sua integração, existe um limite de 10 tokens por hora para cada credencial. Em termos simples: se sua aplicação ficar pedindo token toda hora, ela pode ser bloqueada temporariamente com erro 429.
Você não deve gerar um novo token a cada requisição. Gere 1 token, salve e reutilize até ele expirar.

​
Obtendo o token

curl -X POST https://api-payment.safefypay.com.br/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "grantType": "client_credentials",
    "publicKey": "pk_sandbox_abc123...",
    "secretKey": "sk_sandbox_xyz789..."
  }'
Resposta: 
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "environment": "Sandbox"
  }
}

​
Usando o token

Inclua o token no header Authorization de todas as requisições: 
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
O token expira em 1 hora (3600 segundos). Renove-o antes da expiração para evitar interrupções.

​
Como evitar bloqueio de forma simples

Pense no token como um “ingresso” válido por 1 hora:
  1. Gere o token uma vez.
  2. Salve o accessToken e a data/hora de expiração.
  3. Antes de pedir novo token, verifique se já existe um salvo e ainda válido.
  4. Se ainda estiver válido, use o mesmo token.
  5. Só gere outro quando estiver expirado (ou muito perto de expirar).
Exemplo simples de lógica: 
se existe token salvo E agora < dataExpiracao:
  usar token salvo
senao:
  gerar novo token
  salvar token + dataExpiracao
Uma prática segura é renovar alguns minutos antes da expiração (ex.: 2 a 5 minutos) para evitar falha por diferença de relógio entre servidores.

​
Boas práticas de segurança

Nunca exponha a secretKey

Mantenha a secretKey apenas no backend. Nunca a inclua em código frontend ou repositórios públicos.

Use variáveis de ambiente

Armazene suas credenciais em variáveis de ambiente ou serviços de secrets (AWS Secrets Manager, Vault, etc).

Renove antes de expirar

Implemente logica para renovar o token antes dos 3600 segundos expirarem.

Configure IPs permitidos

No painel Safefy, restrinja o uso das credenciais apenas aos IPs do seu servidor.

​
Erros comuns

CodigoErroSolução
401Credenciais inválidasVerifique publicKey e secretKey
403IP não autorizadoAdicione o IP nas configurações da credencial
429Limite de tokens excedido (auth_rate_limit_exceeded)Reutilize o token já salvo até expirar e respeite o Retry-After

Testar autenticacao

Experimente o endpoint de autenticação no playground.