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

# Authenticatie

> Elke aanroep bevat een API-sleutel, die uw software identificeert, en een ID-token, die de gebruiker identificeert.

De Codaclean API combineert twee inloggegevens.

| Gegeven     | Header                            | Identificeert                        | Verplicht bij                      |
| ----------- | --------------------------------- | ------------------------------------ | ---------------------------------- |
| API-sleutel | `x-api-key: <key>`                | Uw software                          | Elke aanroep, ook `POST /token`    |
| ID-token    | `Authorization: Bearer <idToken>` | De gebruiker en zijn boekhoudkantoor | Elke aanroep behalve `POST /token` |

Het boekhoudkantoor wordt altijd afgeleid uit de ID-token.

U geeft het nooit mee als parameter: een gebruiker ziet altijd alleen de gegevens van zijn eigen kantoor.

## Gebruikersaccounts en bereik van de token

De inloggegevens die u naar `POST /token` stuurt, zijn die van een Codaclean-gebruikersaccount.

Het boekhoudkantoor maakt die accounts zelf aan en beheert ze in zijn [MyCodaclean](https://app.codaclean.io)-platform. Het bepaalt per gebruiker het toegangsniveau en tot welke klanten die gebruiker toegang heeft.

Een ID-token heeft dus hetzelfde bereik als zijn gebruiker:

* **Meestal het hele boekhoudkantoor.** De token geeft toegang tot alle klanten van het kantoor die de gebruiker kan zien.
* **Of alleen een of meer vennootschappen.** Het boekhoudkantoor kan een gebruiker beperken tot bepaalde klanten. De API geeft dan alleen die klanten terug, met hun mandaten en bestanden.

<Tip>
  Een beperkt account gebruikt u doorgaans wanneer niet de boekhouder, maar de eindklant met uw software werkt.

  Het boekhoudkantoor maakt dan een account aan dat beperkt is tot de vennootschap van die klant, zodat uw software uitsluitend de gegevens van die vennootschap ziet.
</Tip>

**Zie ook:** [Toegang tot gegevens](/nl/api/data-access)

## Een ID-token ophalen

Roep [`POST /token`](/nl/api/endpoints/get-token) aan met de inloggegevens van de gebruiker:

| Veld       | Beschrijving                                              |
| ---------- | --------------------------------------------------------- |
| `username` | De Codaclean-gebruikersnaam van de gebruiker.             |
| `password` | Het wachtwoord van de gebruiker, **in Base64 gecodeerd**. |

Het antwoord bevat:

| Veld           | Beschrijving                                                                                          |
| -------------- | ----------------------------------------------------------------------------------------------------- |
| `idToken`      | Stuur deze token mee als `Authorization: Bearer <idToken>` bij elke andere aanroep. **1 uur** geldig. |
| `refreshToken` | Hiermee verkrijgt u een nieuwe `idToken` zonder wachtwoord. **30 dagen** geldig.                      |

<Warning>
  Het wachtwoord moet in Base64 gecodeerd zijn voordat u het verstuurt.

  Codaclean decodeert het wachtwoord: een wachtwoord in platte tekst leidt daardoor tot `500 Authentication failed`.
</Warning>

## De ID-token vernieuwen

De ID-token is 1 uur geldig. Zodra hij verlopen is, geven uw aanroepen `401` terug.

Roep `POST /token` dan opnieuw aan, met alleen de refreshtoken:

| Veld           | Beschrijving                                                                                       |
| -------------- | -------------------------------------------------------------------------------------------------- |
| `refreshToken` | Een refreshtoken die u bij een eerdere aanmelding met gebruikersnaam en wachtwoord hebt ontvangen. |

Het antwoord bevat een nieuwe `idToken`, maar **geen** nieuwe `refreshToken`: gebruik de refreshtoken die u al hebt gewoon verder.

De refreshtoken is 30 dagen geldig. Is hij verlopen, meld u dan opnieuw aan met gebruikersnaam en wachtwoord.

## Tokenfouten

| Status | Betekenis                                                                                                                                                         |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | U hebt noch `username`/`password`, noch `refreshToken` meegestuurd.                                                                                               |
| `403`  | De API-sleutel ontbreekt of is ongeldig.                                                                                                                          |
| `500`  | De authenticatie is mislukt. Het veld `error` bevat de reden die de identiteitsprovider opgeeft (bijvoorbeeld foute inloggegevens of een ongeldige refreshtoken). |

<Note>
  Op dit endpoint wijst een `500` doorgaans op foute inloggegevens of een ongeldige refreshtoken, niet op een serverstoring.
</Note>

## Wie kan de API gebruiken?

* Gebruikers met het toegangsniveau **Enkel portaal** kunnen de API niet gebruiken: hun aanroepen geven `401` terug.
* Gebruikers die geen **Beheerder** zijn, zien geen vertrouwelijke klanten.
* De [scopes](/nl/api/scopes) bepalen wat uw API-sleutel mag doen.

**Zie ook:** [Toegang tot gegevens](/nl/api/data-access)