# Authentication

The Partner API uses the **OAuth2 `client_credentials`** flow (RFC 6749, section 4.4). The partner exchanges its `client_id` and `client_secret` for a short-lived Bearer token and uses it on every other call.

## Get the 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}}
```

The endpoint also accepts an `application/json` body.

**Response:**

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

- `expires_in` is the lifetime in seconds (8 hours).
- `scope` is the intersection of the requested scopes with the credential's permissions.

## Use the token

Send the token on every subsequent call:

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

When the token expires, request a new one at `POST /api/partner/v1/oauth/token`.

## Verify the credential

After obtaining the token, confirm the integration with a sanity call:

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

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

The endpoint accepts any valid partner token and echoes the credential's `partner_id`, so you can confirm it is active and pointing to the partner you expect.

## Token error responses

| HTTP | `error` | When |
|---|---|---|
| `400` | `invalid_request` | Missing `grant_type`, `client_id` or `client_secret` |
| `400` | `unsupported_grant_type` | `grant_type` other than `client_credentials` |
| `401` | `invalid_client` | Wrong `client_id` or `client_secret`, or inactive credential |

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

## Security

- Store the `client_secret` securely. Never expose it in versioned code, front-end or logs.
- The token is short-lived; request a new one whenever needed.
- When possible, restrict the call origin to your credential's allowed IP list.