Authentication

The Integrated API uses OAuth 2.0 client credentials (RFC 6749 §4.4). Your client is a machine identity bound to one CPO partner — there is no end user behind the token.

Get your credentials

Joulo provisions an OAuth client for your partner and gives you a client_id and client_secret, plus the scopes your integration needs. The secret is shown once.

Request a token

POST https://api.joulo.nl/functions/v1/oauth-token

curl -X POST https://api.joulo.nl/functions/v1/oauth-token \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "your-client-id",
    "client_secret": "your-client-secret"
  }'

{
  "access_token": "9f456b04e72e749c...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "cpo:accounts:write cpo:mandates:write cpo:sessions:write cpo:chargers:write"
}

The token is valid for one hour. There is no refresh token — for machine-to-machine access you simply request a new token when the old one expires (re-presenting your credentials).

You may narrow a token to a subset of your scopes by passing a space-separated scope parameter; omit it to receive all scopes granted to your client.

Call the API

Send the token as a bearer token on every request:

curl https://api.joulo.nl/functions/v1/api/v1/accounts \
  -H "Authorization: Bearer 9f456b04e72e749c..."

Scopes

Access is fail-closed: an endpoint you lack the scope for returns 403 Insufficient scope, and unknown routes return 404.

Errors