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

# Authentication

> Every call carries an API key that identifies your software and an ID token that identifies the user.

The Codaclean API uses two credentials together.

| Credential | Header                            | Identifies                         | Required on                         |
| ---------- | --------------------------------- | ---------------------------------- | ----------------------------------- |
| API key    | `x-api-key: <key>`                | Your software                      | Every call, including `POST /token` |
| ID token   | `Authorization: Bearer <idToken>` | The user and their accounting firm | Every call except `POST /token`     |

The accounting firm is always derived from the ID token.

You never send it as a parameter: a user only ever sees their own firm's data.

## User accounts and token scope

The credentials sent to `POST /token` are those of a Codaclean user account.

The accounting firm creates and manages these accounts itself, in its [MyCodaclean](https://app.codaclean.io) platform: it chooses each user's access level and which customers they can access.

The scope of an ID token is therefore that of its user:

* **Usually, the whole accounting firm.** The token gives access to all the firm's customers the user can see.
* **Or one or more companies only.** The accounting firm can restrict a user to specific customers. The API then only returns those customers, with their mandates and files.

<Tip>
  A restricted account is typically used when your software is used by the end customer rather than by the accountant.

  The accounting firm creates an account restricted to that customer's company, and your software only ever sees that company's data.
</Tip>

**See also:** [Data access](/api/data-access)

## Get an ID token

Call [`POST /token`](/api/endpoints/get-token) with the user's credentials:

| Field      | Description                                 |
| ---------- | ------------------------------------------- |
| `username` | The user's Codaclean login.                 |
| `password` | The user's password, **encoded in Base64**. |

The response contains:

| Field          | Description                                                                             |
| -------------- | --------------------------------------------------------------------------------------- |
| `idToken`      | Send it as `Authorization: Bearer <idToken>` on every other call. Valid for **1 hour**. |
| `refreshToken` | Use it to get a new `idToken` without the password. Valid for **30 days**.              |

<Warning>
  The password must be Base64-encoded before you send it.

  Codaclean decodes it, so a plain-text password fails with `500 Authentication failed`.
</Warning>

## Refresh the ID token

The ID token is valid for 1 hour. When it expires, calls return `401`.

Call `POST /token` again with the refresh token only:

| Field          | Description                                                     |
| -------------- | --------------------------------------------------------------- |
| `refreshToken` | A refresh token returned by a previous username/password login. |

The response contains a new `idToken`. It does **not** contain a new `refreshToken`: keep using the one you have.

The refresh token is valid for 30 days. When it expires, log in again with the username and password.

## Token errors

| Status | Meaning                                                                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Neither `username`/`password` nor `refreshToken` was sent.                                                                                               |
| `403`  | Missing or invalid API key.                                                                                                                              |
| `500`  | Authentication failed. The `error` field gives the reason reported by the identity provider (for example wrong credentials or an invalid refresh token). |

<Note>
  On this endpoint, a `500` usually means wrong credentials or an invalid refresh token, not a server failure.
</Note>

## Who can use the API

* Users with the **Portal only** access level cannot use the API: their calls return `401`.
* Users who are not **Administrator** do not see confidential customers.
* What your API key may do is controlled by [scopes](/api/scopes).

**See also:** [Data access](/api/data-access)