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

# Autenticação

> Autenticação em sandbox é estruturalmente idêntica à produção.

## Visão Geral

A autenticação em sandbox usa as mesmas duas camadas que produção:

1. **Certificado X.509 (mTLS)** — entregue pelo NTX Pay no onboarding.
2. **OAuth 2.0 `client_credentials`** — `clientId` + `clientSecret` recebidos no signup.

Em conjunto, retornam um **JWT** (validade 10 minutos) usado nos demais endpoints como `Authorization: Bearer ...`.

<Info>
  As credenciais de sandbox são **distintas** das de produção. Se você usar credenciais de produção contra `https://sandbox.mx.ntxpay.com`, receberá `401`. O contrato HTTP é idêntico — o que muda é o par certificado + clientId/clientSecret.
</Info>

## Obter Token

### POST /api/auth/token

```bash theme={"system"}
curl -X POST https://sandbox.mx.ntxpay.com/api/auth/token \
  -H "X-SSL-Client-Cert: $ENCODED_CERT" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "qr-93-550e8400",
    "clientSecret": "a1b2c3d4e5f6g7h8"
  }'
```

#### Response (201)

```json theme={"system"}
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 600,
  "scope": "email profile"
}
```

## Usar o Token

Em uma conta sandbox, qualquer chamada autenticada simula um pipeline completo sem mover dinheiro real:

```bash theme={"system"}
curl -X POST https://sandbox.mx.ntxpay.com/api/spei/cash-out \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amountCentavos": 15000,
    "destinationClabe": "012180001234567890",
    "beneficiaryName": "Maria Lopez",
    "externalId": "test-001"
  }'
```

A resposta é sempre `201 Created` com `status: PENDING`. O resultado final (confirmação ou falha) chega via webhook após \~1 segundo. Veja [Cenários](/pt-br/sandbox/scenarios) para forçar resultados específicos.

## Renovação

O token expira em **10 minutos (600s)**. Não há refresh token — gere um novo via `POST /api/auth/token` antes de expirar.

<Warning>
  Em alta carga, gere um token por worker e renove a cada \~8 minutos para evitar `401` por expiração.
</Warning>

## Erros Comuns

| Código | Causa                              | Solução                                                            |
| ------ | ---------------------------------- | ------------------------------------------------------------------ |
| `400`  | `X-SSL-Client-Cert` ausente        | Configure NGINX/ALB para repassar o certificado                    |
| `401`  | `clientId`/`clientSecret` inválido | Reconfira credenciais; certifique-se de estar usando as de sandbox |
| `401`  | Certificado expirado/revogado      | Solicite renovação ao NTX Pay                                      |

## Documentação detalhada

Para o passo a passo completo (encoding do certificado, exemplos em múltiplas linguagens, etc.) veja [Autenticação](/pt-br/guides/authentication) no guia geral — a única diferença é a base URL `https://sandbox.mx.ntxpay.com`.