> ## Documentation Index
> Fetch the complete documentation index at: https://chargecloud.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> How to authenticate with the chargecloud APIs using OAuth 2.0.

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 <a href="https://support.chargecloud.de/hc/de/articles/33696062181789" target="_blank" rel="noopener noreferrer"><strong>chargecloud Help Center</strong></a>.

<CardGroup cols={1}>
  <Card title="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.
  </Card>

  <Card title="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.
  </Card>
</CardGroup>

<Info>
  The full token endpoint reference is available in the [Core API documentation](/api/core-api).
</Info>

***

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

<Warning>
  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**.
</Warning>

***

## Get a token

```http title="1 · Request token" theme={null}
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"
}
```

```json title="2 · Response" theme={null}
{
  "access_token": "<jwt>",
  "refresh_token": "<token>",
  "token_type": "Bearer",
  "expires_in": 3600
}
```

```http title="3 · Call the API" theme={null}
GET /api/v1/...
Authorization: Bearer <access_token>
```

***

## Common authentication-related responses

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


## Related topics

- [Introduction](/api/core-api/index.md)
- [Contract management](/contract-management.md)
- [Asset management](/asset-management.md)