# Autenticação

A Partner API usa o fluxo **OAuth2 `client_credentials`** (RFC 6749, seção 4.4). O parceiro troca o seu `client_id` e o seu `client_secret` por um token Bearer de curta duração e usa esse token em todas as demais chamadas.

## Obter o token

```http
POST /api/partner/v1/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id={{client_id}}&client_secret={{client_secret}}
```

O endpoint também aceita corpo `application/json`.

**Resposta:**

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "expires_in": 28800,
  "scope": "account:read pix:write"
}
```

- `expires_in` é o tempo de validade em segundos (8 horas).
- `scope` é a interseção dos escopos solicitados com as permissões da credencial.

## Usar o token

Envie o token em todas as chamadas seguintes:

```http
Authorization: Bearer {{access_token}}
```

Quando o token expirar, basta solicitar um novo em `POST /api/partner/v1/oauth/token`.

## Verifique a credencial

Depois de obter o token, confirme a integração com uma chamada de sanidade:

```http
GET /api/partner/v1/ping
Authorization: Bearer {{access_token}}
```

```json
{ "status": "ok", "partner_id": 42 }
```

O endpoint aceita qualquer token de parceiro válido e ecoa o `partner_id` da credencial, para confirmar que ela está ativa e apontando para o parceiro esperado.

## Respostas de erro do token

| HTTP | `error` | Quando ocorre |
|---|---|---|
| `400` | `invalid_request` | Falta `grant_type`, `client_id` ou `client_secret` |
| `400` | `unsupported_grant_type` | `grant_type` diferente de `client_credentials` |
| `401` | `invalid_client` | `client_id` ou `client_secret` incorretos, ou credencial inativa |

```json
{
  "error": "invalid_client",
  "error_description": "Client authentication failed"
}
```

## Segurança

- Guarde o `client_secret` em local seguro. Nunca o exponha em código versionado, front-end ou logs.
- O token tem validade curta; solicite um novo sempre que necessário.
- Restrinja, quando possível, a origem das chamadas à lista de IPs autorizados da sua credencial.