> ## Documentation Index
> Fetch the complete documentation index at: https://docs.safefypay.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> Como autenticar suas requisições na API Safefy

A Safefy oferece dois modos de autenticação. Escolha o que melhor se adapta à sua integração:

|                               | **v2 (Direto, recomendado)**                          | **v1 (Legacy)**                                                       |
| ----------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------- |
| Como funciona                 | Envia `X-Api-Key` + `X-Api-Secret` em cada requisição | Gera token JWT via `/v1/auth/token` e envia no header `Authorization` |
| Passo extra de autenticação   | Não                                                   | Sim                                                                   |
| Limite de rate limit de token | Não se aplica                                         | 10 tokens/hora por credencial                                         |
| Renovação de token            | Não precisa                                           | Necessário a cada hora                                                |
| Recomendado para              | Todas as novas integrações                            | Integrações existentes (manter como está)                             |

<Info>
  As permissões da credencial (leitura/escrita por módulo, incluindo saques) estão detalhadas em [Permissões da credencial](/credential-permissions).
</Info>

## Autenticação v2 (Direto, recomendado)

Envie suas credenciais diretamente em cada requisição via dois headers. Nenhum passo de geração de token é necessário.

```bash theme={null}
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "X-Api-Key: pk_sandbox_abc123..." \
  -H "X-Api-Secret: sk_sandbox_xyz789..."
```

<Tip>
  Este é o modo recomendado para novas integrações. Sem tokens, sem expiração, sem lógica de renovação.
</Tip>

### Usando o SDK Node.js (v2)

```typescript theme={null}
import { SafefyPaymentSDK } from "safefy-sdk-node";

const safefy = new SafefyPaymentSDK({
  publicKey: process.env.SAFEFY_PUBLIC_KEY!,
  secretKey: process.env.SAFEFY_SECRET_KEY!,
  authMode: "v2", // <- sem geração de token
});

// Pode chamar diretamente, sem chamar authenticate() antes
const transactions = await safefy.transactions.list();
```

***

## Autenticação v1 (OAuth2, legacy)

<Warning>
  O modo v1 ainda é suportado, mas novas integrações devem utilizar o **v2** acima.
</Warning>

### Como funciona

```mermaid theme={null}
sequenceDiagram
    participant App as Sua Aplicação
    participant Safefy as API Safefy
    
    App->>Safefy: POST /v1/auth/token (credenciais)
    Safefy-->>App: Token JWT (expira em 1h)
    App->>Safefy: GET /v1/transactions (Authorization: Bearer token)
    Safefy-->>App: Dados da transação
```

### 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`.

<Warning>
  Você não deve gerar um novo token a cada requisição. Gere 1 token, salve e reutilize até ele expirar.
</Warning>

### Obtendo o token

```bash theme={null}
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:**

```json theme={null}
{
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "tokenType": "Bearer",
    "expiresIn": 3600,
    "environment": "Sandbox"
  }
}
```

### Usando o token

Inclua o token no header `Authorization` de todas as requisições:

```bash theme={null}
curl https://api-payment.safefypay.com.br/v1/transactions \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

<Warning>
  O token expira em **1 hora** (3600 segundos). Renove-o antes da expiração para evitar interrupções.
</Warning>

### 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:

```text theme={null}
se existe token salvo E agora < dataExpiracao:
  usar token salvo
senao:
  gerar novo token
  salvar token + dataExpiracao
```

<Tip>
  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.
</Tip>

***

## Boas práticas de segurança

<CardGroup cols={2}>
  <Card title="Nunca exponha a secretKey" icon="shield">
    Mantenha a secretKey apenas no backend. Nunca a inclua em código frontend ou repositórios públicos.
  </Card>

  <Card title="Use variáveis de ambiente" icon="lock">
    Armazene suas credenciais em variáveis de ambiente ou serviços de secrets (AWS Secrets Manager, Vault, etc).
  </Card>

  <Card title="Renove antes de expirar" icon="rotate">
    Implemente logica para renovar o token antes dos 3600 segundos expirarem.
  </Card>

  <Card title="Configure IPs permitidos" icon="network-wired">
    No painel Safefy, restrinja o uso das credenciais apenas aos IPs do seu servidor.
  </Card>
</CardGroup>

***

## Erros comuns

| Codigo | Erro                                                   | Solução                                                           |
| ------ | ------------------------------------------------------ | ----------------------------------------------------------------- |
| 401    | Credenciais inválidas                                  | Verifique publicKey e secretKey                                   |
| 403    | IP não autorizado                                      | Adicione o IP nas configurações da credencial                     |
| 429    | Limite de tokens excedido (`auth_rate_limit_exceeded`) | Reutilize o token já salvo até expirar e respeite o `Retry-After` |

<Card title="Testar autenticacao" icon="play" href="/api-reference/auth/token">
  Experimente o endpoint de autenticação no playground.
</Card>