Skip to main content

How to get Access to the API

YourIn 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.

Back to top