Authentication - chargecloud Developer Hub

All requests to the chargecloud APIs must be authenticated. To get access, you first request an access token from the OAuth token endpoint using your credentials. Your system then sends this token with every API call and requests a new one before it expires. Requests that are missing credentials, use an invalid or expired token, or lack the required permissions are rejected with the appropriate HTTP error.

Before you start

Two credential options are supported for the OAuth token endpoint. Both are set up outside the API, in the chargecloud OS. For step-by-step setup instructions, see the chargecloud Help Center.

A — Sign in as a person: chargecloud OS user credentials

Use this when a real team member is behind the integration. An administrator creates a user in the chargecloud OS and assigns the correct role. The role then determines the scopes available to that user.Best for: integrations your team builds and maintains itself, where you want to see in the chargecloud OS who did what.Technical: email = username, password = password.

B — Sign in as a system: API key

Use this when there is no person involved — for example a nightly job that syncs data on its own. An administrator creates an API key in the chargecloud OS and assigns it a role.Best for: automated jobs and machine-to-machine integrations that run without anyone clicking a button.Technical: public key = username, private key = password.

The full token endpoint reference is available in the Core API documentation.

The `context` parameter

The chargecloud OS serves multiple entity types within a single tenant. The optional context parameter on the token request tells the IDP which entity type to look up credentials against.

Supported values

Value	Entity type	When to use
`employer`	Employer	Authenticating on behalf of an employer. Sets `sub_type: employer` in the issued JWT.
`contract`	Contract	Authenticating on behalf of a contract entity. Sets `sub_type: contract` in the issued JWT.
(omitted)	Default	Falls back to the `entityType` configured on the OAuth client.

When context is provided, it takes precedence over the OAuth client’s static entityType configuration. Make sure the value matches the entity type your credentials belong to, or the authentication lookup will fail with a 401.

Get a token

1 · Request token

POST /api/v1/oauth/token
Content-Type: application/json

{
  "username": "<email or public key>",
  "password": "<password or private key>",
  "tenant":   "<your-tenant-id>",
  "context":  "employer"
}

2 · Response

{
  "access_token": "<jwt>",
  "refresh_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600
}

3 · Call the API

GET /api/v1/...
Authorization: Bearer <access_token>

Code	Status	Typical cause and action
`400`	Invalid request	A required field is missing or has an invalid value. Check that `username`, `password`, and `tenant` are present, and that `context` (if provided) is correctly formatted.
`401`	Invalid or missing token	Credentials are invalid or the token has expired. Re-authenticate to obtain a fresh token. If you are passing `context`, confirm it matches the entity type of the authenticating account.
`403`	Insufficient permissions	The token is valid but the entity does not hold the required permission for this endpoint. Grant the missing permission in the chargecloud OS.
`429`	Too many requests	The rate limit has been exceeded. Wait before retrying and implement exponential backoff in your integration.

​Before you start

A — Sign in as a person: chargecloud OS user credentials

B — Sign in as a system: API key

​The context parameter

​Supported values

​Get a token

​Common authentication-related responses

Before you start

The `context` parameter

Supported values

Get a token

Common authentication-related responses