# How to get Access to the API

In order to get access to the API's of Adhese, you require a service account, your service account lets your backend system call the Adhese API without a user login. It uses the OAuth 2.0 **client credentials** flow: you exchange a client ID and secret for a short-lived access token, then include that token in every API request.

## Prerequisites

Your Adhese support agent will provide:

- **Client ID** — the identifier for your service account (e.g. `my-company-integration`)
- **Client secret** — treat this like a password; keep it out of source control
- **Realm** — your Adhese realm name (e.g. `customer-name`)
- **Region** — determines the auth server URL (see below)

## Token endpoint

```
POST https://auth.{region}.adhese.org/realms/{realm}/protocol/openid-connect/token
```

| Region | Value |
|---|---|
| Europe West | `we` |
| Central US | `cus` |

## Getting a token

Send a `POST` request with `Content-Type: application/x-www-form-urlencoded`.

**curl**

```bash
curl -X POST \
  "https://auth.we.adhese.org/realms/customer-name/protocol/openid-connect/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=my-customer-integration" \
  -d "client_secret=<your-secret>" \
  -d "scope=adhese-api"
```

**Python**

```python
import requests

response = requests.post(
    "https://auth.we.adhese.org/realms/customer-name/protocol/openid-connect/token",
    data={
        "grant_type":    "client_credentials",
        "client_id":     "my-customer-integration",
        "client_secret": "<your-secret>",
        "scope":         "adhese-api",  # or "adhese-api ratecard"
    },
)
token = response.json()["access_token"]
```

**Response**

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5...",
  "token_type": "Bearer",
  "expires_in": 300,
  "scope": "adhese-api"
}
```

## Scopes

The `scope` parameter controls which permissions appear in your token. Your support agent configures which scopes are available to your service account.

| Scope | Use when |
|---|---|
| `adhese-api` | Calling the Adhese API |
| `ratecard` | Calling the Ratecard API |

To request multiple scopes, separate them with a space:

```
scope=adhese-api ratecard
```

Only request scopes for the APIs you will actually call. Roles for a scope you did not request will not appear in the token even if they were granted.

## Token contents

The access token is a signed JWT. When decoded, it contains your granted permissions under `permissions.adhese-api` and/or `permissions.ratecard`:

```json
{
  "permissions": {
    "adhese-api": [
      "booking:view",
      "campaign:view",
      "creative:view"
    ]
  }
}
```

The exact roles listed depend on what your support agent has configured for your service account.

## Calling the API

Pass the token as a `Bearer` in the `Authorization` header of every request:

```bash
curl "https://api.adhese.org/..." \
  -H "Authorization: Bearer <access_token>"
```

## Token expiry

Tokens expire after a while. Cache the token and reuse it across requests for its remaining lifetime. When it expires, request a new one using the same client credentials — the client credentials flow has no refresh token.

A simple approach: track the `expires_in` value from the token response, subtract a small buffer (e.g. 30 seconds), and request a new token when that time has elapsed.