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 
 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 
 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 
 {
 "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 : 
 {
 "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: 
 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.