> For the complete documentation index, see [llms.txt](https://docs.cootje.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cootje.com/cootje-api/authenticatie/token-ophalen.md).

# Token Ophalen

Zo haal je met een API-account een token op voor de Cootje API, gebruik je het bij aanroepen en houd je het geldig.

De Cootje API werkt met een Bearer-token. Je haalt dat token op door in te loggen met een API-account en stuurt het daarna mee bij elke aanroep. Deze pagina laat zien hoe je een token ophaalt, gebruikt en geldig houdt.

Alle aanroepen gaan naar `https://mijn.cootje.com/api`. Een overzicht van alle aanroepen staat in de [API-referentie (Swagger)](https://mijn.cootje.com/api/swagger).

## Wat je nodig hebt

Je hebt een **API-account** nodig in jullie Cootje-omgeving: een persoon die alleen bedoeld is voor een koppeling.

* Een beheerder maakt het account aan als nieuwe persoon, kiest bij **Inloggen toegestaan?** voor **Ja** en vinkt **Is API-account?** aan.
* Op het e-mailadres van het account komt een e-mail binnen om het wachtwoord in te stellen. Gebruik dus een adres waarvan je de post kunt lezen.
* Een API-account hoeft geen tweestapsverificatie te doorlopen en kan niet inloggen in de webapplicatie.
* Het account mag via de API precies wat die persoon in Cootje mag. Geef het alleen de rechten die de koppeling nodig heeft.

{% hint style="warning" %}
Gebruik geen persoonlijk account voor een koppeling. Een gewoon account met rechten moet bij het inloggen een code voor tweestapsverificatie opgeven, en dat kan een geautomatiseerde koppeling niet.
{% endhint %}

## Token ophalen

Stuur het e-mailadres en wachtwoord van het API-account naar `POST /iam/auth/login`:

```bash
curl -X POST "https://mijn.cootje.com/api/iam/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: text/plain" \
  -d '{"email": "koppeling@voorbeeld.nl", "password": "JOUW_WACHTWOORD"}'
```

Bij een geslaagde aanmelding is het antwoord het token zelf, als platte tekst. Het is geen JSON-object met een veld erin:

```
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
```

Mogelijke antwoorden:

| Code  | Betekenis                                                                              | Wat je doet                                                           |
| ----- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `200` | Aangemeld; het antwoord is het token                                                   | Bewaar het token en gebruik het bij de volgende aanroepen             |
| `401` | E-mailadres of wachtwoord klopt niet, of het account is niet aan een persoon gekoppeld | Controleer de gegevens of vraag de beheerder het account na te kijken |
| `403` | Het account vraagt om tweestapsverificatie                                             | Het account is geen API-account; laat **Is API-account?** aanvinken   |
| `428` | Het account moet eerst tweestapsverificatie instellen                                  | Het account is geen API-account; laat **Is API-account?** aanvinken   |

## Token gebruiken

Stuur het token bij elke aanroep mee in de `Authorization`-header, voorafgegaan door `Bearer` en een spatie:

```bash
curl "https://mijn.cootje.com/api/iam/auth/userinfo" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

`GET /iam/auth/userinfo` geeft terug met welk account en in welke omgeving je bent aangemeld. Bij een API-account staat `isApiAccount` op `true`.

Wil je alleen weten of een token nog geldig is, gebruik dan `GET /iam/auth/validate`. Het antwoord is `204` bij een geldig token en `401` bij een ongeldig of verlopen token.

## Token geldig houden

Een token is **10 minuten** geldig. Daarna geeft elke aanroep `401`.

Je kunt een token verlengen zolang het nog geldig is. Stuur het huidige token naar `POST /iam/auth/refreshtoken`; het antwoord is een nieuw token dat weer 10 minuten geldig is:

```bash
curl -X POST "https://mijn.cootje.com/api/iam/auth/refreshtoken" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Accept: text/plain"
```

Twee manieren om hiermee te werken:

* **Korte taak** (bijvoorbeeld een nachtelijke export): log in aan het begin van de taak en gebruik dat token tot de taak klaar is. Duurt de taak langer dan een paar minuten, verleng dan tussendoor.
* **Doorlopende koppeling:** verleng het token ruim voor het verloopt, bijvoorbeeld elke 5 minuten. Krijg je toch een `401`, log dan opnieuw in.

## Werken met meerdere omgevingen

Een token geldt voor één omgeving. Is het API-account aan meerdere omgevingen gekoppeld, dan krijg je bij het inloggen een token voor de voorkeursomgeving van het account. Hoe je voor elke andere omgeving een token ophaalt, lees je op [Multi Tenancy](https://docs.cootje.com/cootje-api/authenticatie/multi-tenancy.md).

## Veilig omgaan met je gegevens

* Bewaar het wachtwoord van het API-account in een kluis voor geheimen, niet in code of in een gedeeld document.
* Maak per koppeling een eigen API-account. Stopt een koppeling, dan kan de beheerder dat ene account intrekken zonder dat andere koppelingen uitvallen.
* Zet een token nooit in een webadres en deel het niet per e-mail of chat. Wie het token heeft, kan tot het verloopt alles wat het account mag.
