Autenticação e Autorização

🔐 Métodos de Autenticação

1. JWT Bearer Tokens

Login

POST /api/v1/auth/login
Content-Type: application/json

{
  "email": "[email protected]",
  "password": "password123"
}

Resposta:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIs...",
    "refresh_token": "rt_abc123xyz",
    "expires_in": 3600,
    "token_type": "Bearer"
  }
}

Uso do Token

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

2. API Keys

Formato

pk_test_1234567890abcdef  # Test environment
pk_live_1234567890abcdef  # Live environment

Uso

Authorization: Bearer pk_live_1234567890abcdef

🔑 Gerenciamento de Tokens

Refresh Token

POST /api/v1/auth/refresh
Content-Type: application/json

{
  "refresh_token": "rt_abc123xyz"
}

Logout

POST /api/v1/auth/logout
Authorization: Bearer {token}

Revogar Token

POST /api/v1/auth/revoke
Authorization: Bearer {token}

{
  "token": "specific_token_to_revoke"
}

👥 Controle de Acesso (RBAC)

Roles Disponíveis

Role	Permissões
admin	Acesso total ao sistema
merchant	Gerenciar próprios pagamentos
readonly	Apenas leitura de dados
webhook	Apenas receber webhooks

Scopes de Permissão

Scope	Descrição
payments:read	Ler pagamentos
payments:write	Criar/atualizar pagamentos
payments:refund	Processar reembolsos
analytics:read	Acessar relatórios
admin:config	Gerenciar configurações
webhooks:receive	Receber webhooks

🛡️ Segurança

Headers de Segurança

X-API-Version: v1
X-Request-ID: req_123456789
User-Agent: MyApp/1.0

Rate Limiting

• Headers retornados em cada resposta:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Validação de Origem

Origin: https://yourdomain.com
Referer: https://yourdomain.com/checkout

🔒 Webhook Authentication

Validação de Assinatura

const crypto = require('crypto');

function validateWebhook(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === expectedSignature;
}

Headers de Webhook

X-Signature: sha256=abcdef123456...
X-Timestamp: 1640995200
X-Event-Type: payment.succeeded

⚠️ Códigos de Erro de Autenticação

Código	Descrição
401	Token inválido ou expirado
403	Permissões insuficientes
429	Rate limit excedido

Exemplos de Erro

{
  "success": false,
  "error": {
    "code": "INVALID_TOKEN",
    "message": "The provided token is invalid or expired",
    "details": "Token expired at 2024-12-12T10:30:00Z"
  }
}

---

Documentação atualizada: December 2024