# Authentication

The Partner API uses **OAuth 2.0 client credentials**. You exchange a client secret for a signed bearer token
(RS256 JWT) and send that token on every request.

## Test and live secrets

Client secrets carry their environment in the prefix:

| Prefix | Environment | Use |
| --- | --- | --- |
| `aiv_test_` | `partner_test` | Development and testing. Isolated test data. |
| `aiv_live_` | `production` | Real jobs and candidates. |

The prefix must match the environment of the client it belongs to, otherwise the token request is rejected.
Clients issued before prefixes were introduced have unprefixed secrets; they keep working but must send
`client_id` too.

Keep secrets on your server. Never ship them in a browser or mobile app.

## Requesting a token

`POST /v1/auth/token` accepts any of these:

- a JSON body: `{"grant_type": "client_credentials", "client_secret": "...", "client_id": "..."}`
- a form body (`application/x-www-form-urlencoded`) with the same fields
- HTTP Basic auth with `client_id:client_secret`

`grant_type` must be `client_credentials`. `client_id` is optional with a prefixed secret.

```bash
curl -X POST https://api.aiviue.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type": "client_credentials", "client_secret": "aiv_test_..."}'
```

The response is plain JSON (not wrapped in the response envelope):

```json
{ "access_token": "...", "token_type": "Bearer", "expires_in": 3600, "scope": "jobs:read jobs:write" }
```

Invalid credentials return `401`.

## Using the token

```http
Authorization: Bearer <access_token>
```

Tokens expire after `expires_in` seconds (one hour). Reuse a token until it is close to expiry; don't request
one per call.

## Scopes

Your client is granted a fixed set of scopes when it is created. The token's `scope` field lists them. Calls
outside your scopes return `403`.

| Scope | Allows |
| --- | --- |
| `jobs:read` | Read jobs |
| `jobs:write` | Create and update jobs |
| `candidates:read` | Read candidates and scores |
| `candidates:write` | Submit selection decisions |
| `webhooks:read` | Read webhook subscriptions |
| `webhooks:write` | Manage webhook subscriptions |
| `webhooks:manage` | Full webhook access (includes `webhooks:read` and `webhooks:write`) |
| `analytics:read` | Read partner analytics |
| `analytics:write` | Write partner analytics events |
| `partner_test:reset` | Reset your own `partner_test` data (test environment only) |

## Verifying tokens yourself

Tokens are signed with RS256. The public keys are published at
`GET /v1/auth/.well-known/jwks.json`; the issuer is `https://api.aiviue.com`.

## Revoking credentials

`POST /v1/auth/token/revoke` with a JSON body `{"client_id": "...", "client_secret": "..."}` deactivates the
client. Use it if a secret leaks, then ask us for a new one.