Authentication

Every request to the Joulo API must include a valid token. The API supports two authentication methods: personal API tokens for simple integrations and OAuth2 for third-party applications.

API tokens

The simplest way to authenticate. Generate a token from the Joulo dashboard and include it in your requests.

Activate your token

Click Activate to generate your personal API token. Copy it and store it securely.

Store your API token in an environment variable or secrets manager. Never hard-code it in source code or commit it to a repository.

Using the token

Send your token in the Authorization header on every request:

curl https://api.joulo.nl/functions/v1/api/chargers \
  -H "Authorization: Bearer YOUR_API_TOKEN"

The ?token= query-string method that earlier versions of these docs documented is no longer supported and will return 401. Tokens in URLs leak via server, proxy, and browser logs and via the Referer header. Use the Authorization header — Home Assistant's rest: integration supports a headers: block, see the Home Assistant guide.

Token management

Rotate your token — Generate a new token from the dashboard at any time. The old token is immediately invalidated.
Deactivate your token — Remove API access entirely from Settings → API → Deactivate.

OAuth2

For third-party applications that act on behalf of Joulo users, the API supports OAuth2 with PKCE (Proof Key for Code Exchange).

OAuth2 tokens use scopes to limit access:

Scope	Description
`chargers:read`	Access charger data via `GET /chargers`
`chargers:write`	Add chargers via `POST /chargers`
`sessions:read`	Access session data via `GET /sessions`
`energy:read`	Access energy statistics via `GET /energy`

See the OAuth2 guide for the full authorization flow.

Error responses

When a request is made with a missing or invalid token:

{
  "error": "Missing or invalid API token"
}

When a valid OAuth2 token lacks the required scope:

{
  "error": "Insufficient scope",
  "required_scope": "chargers:read"
}

HTTP status	Cause
`401 Unauthorized`	Token is missing, invalid, or expired.
`403 Forbidden`	Token is valid but lacks the required scope for this endpoint.