Authentication
Authenticate requests to the Joulo API with an API token or OAuth2
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.
Open the dashboard
Log in at joulo.nl/dashboard.
Navigate to API settings
Go to Settings → API.
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
You can authenticate in two ways:
Authorization header (recommended):
curl https://api.joulo.nl/functions/v1/api/chargers \
-H "Authorization: Bearer YOUR_API_TOKEN"Query parameter (for simple integrations like Home Assistant):
https://api.joulo.nl/functions/v1/api/chargers?token=YOUR_API_TOKENThe query parameter method is convenient for Home Assistant REST integrations where setting custom headers is verbose. For all other use cases, prefer the Authorization header.
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. |