# Autenticación

La Partner API usa el flujo **OAuth2 `client_credentials`** (RFC 6749, sección 4.4). El socio intercambia su `client_id` y su `client_secret` por un token Bearer de corta duración y lo usa en todas las demás llamadas.

## Obtener el 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}}
```

El endpoint también acepta un cuerpo `application/json`.

**Respuesta:**

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

- `expires_in` es la validez en segundos (8 horas).
- `scope` es la intersección de los alcances solicitados con los permisos de la credencial.

## Usar el token

Envíe el token en cada llamada siguiente:

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

Cuando el token expire, solicite uno nuevo en `POST /api/partner/v1/oauth/token`.

## Verifique la credencial

Después de obtener el token, confirme la integración con una llamada de sanidad:

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

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

El endpoint acepta cualquier token de socio válido y devuelve el `partner_id` de la credencial, para confirmar que está activa y apunta al socio esperado.

## Respuestas de error del token

| HTTP | `error` | Cuándo |
|---|---|---|
| `400` | `invalid_request` | Falta `grant_type`, `client_id` o `client_secret` |
| `400` | `unsupported_grant_type` | `grant_type` distinto de `client_credentials` |
| `401` | `invalid_client` | `client_id` o `client_secret` incorrectos, o credencial inactiva |

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

## Seguridad

- Guarde el `client_secret` de forma segura. Nunca lo exponga en código versionado, front-end o registros.
- El token es de corta duración; solicite uno nuevo cuando sea necesario.
- Cuando sea posible, restrinja el origen de las llamadas a la lista de IP autorizadas de su credencial.