> 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/multi-tenancy.md).

# Multi Tenancy

Zo vraag je met één API-account voor elke omgeving (tenant) een eigen token op.

Cootje is multi-tenant: elke organisatie werkt in een eigen omgeving, met eigen gegevens en eigen rechten. Een token geldt altijd voor één omgeving. Deze pagina laat zien hoe je met één API-account voor elke omgeving een eigen token ophaalt.

## Hoe het werkt

* Eén inlog (e-mailadres en wachtwoord) kan aan meerdere omgevingen gekoppeld zijn. In elke omgeving is het account een eigen persoon met eigen rechten.
* Bij het inloggen krijg je een token voor de voorkeursomgeving van het account. Is er geen voorkeur ingesteld, dan is het de eerste omgeving waaraan het account gekoppeld is.
* Met dat token vraag je een token voor een andere omgeving op. Het eerste token blijft daarnaast geldig tot het verloopt.
* De omgeving zit in het token. Een aanroep werkt dus altijd op de omgeving van het token dat je meestuurt.

## Wat je nodig hebt

* Een API-account en een token, zoals beschreven op [Token Ophalen](https://docs.cootje.com/cootje-api/authenticatie/token-ophalen.md).
* Het account moet in elke omgeving waarmee je wilt werken als persoon bestaan, gekoppeld aan dezelfde inlog. Dat regelt de beheerder.
* Laat in elke omgeving bij die persoon **Is API-account?** aanvinken en geef per omgeving alleen de rechten die de koppeling daar nodig heeft.

## Omgevingen opvragen

Vraag met `GET /iam/environments/list` op bij welke omgevingen het account kan:

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

Het antwoord is een lijst met één regel per omgeving. De waarden hieronder zijn een voorbeeld:

```json
[
  {
    "_id": "665f1c2a9b3e4d0012ab34cd",
    "description": "Voorbeeld Zorg B.V.",
    "environment": "voorbeeldzorg",
    "isFavorite": true,
    "logoUri": null
  },
  {
    "_id": "665f1c2a9b3e4d0012ab34ce",
    "description": "Voorbeeld Detachering B.V.",
    "environment": "voorbeelddetachering",
    "isFavorite": false,
    "logoUri": null
  }
]
```

| Veld          | Betekenis                                                                               |
| ------------- | --------------------------------------------------------------------------------------- |
| `_id`         | Het kenmerk van de omgeving. Dit gebruik je om een token voor die omgeving op te vragen |
| `description` | De naam van de omgeving zoals gebruikers die zien                                       |
| `environment` | De technische naam van de omgeving                                                      |
| `isFavorite`  | `true` bij de voorkeursomgeving van het account                                         |
| `logoUri`     | Het adres van het logo van de omgeving, als dat er is                                   |

## Token opvragen voor een andere omgeving

Stuur je huidige token naar `GET /iam/auth/{environmentId}/token`, met de `_id` van de gewenste omgeving op de plek van `{environmentId}`:

```bash
curl "https://mijn.cootje.com/api/iam/auth/665f1c2a9b3e4d0012ab34ce/token" \
  -H "Authorization: Bearer JOUW_TOKEN" \
  -H "Accept: text/plain"
```

Het antwoord is een nieuw token voor die omgeving, als platte tekst. Gebruik dat token bij alle aanroepen die over die omgeving gaan.

Controleer met `GET /iam/auth/userinfo` voor welke omgeving een token geldt: `environment` bevat de technische naam en `environmentName` de naam van de omgeving.

| Code  | Betekenis                                                                                      | Wat je doet                                                                   |
| ----- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `200` | Het antwoord is het token voor de gevraagde omgeving                                           | Gebruik dit token voor die omgeving                                           |
| `401` | Je huidige token is verlopen, of het account is in die omgeving niet aan een persoon gekoppeld | Log opnieuw in, of vraag de beheerder het account in die omgeving te koppelen |

## Alle omgevingen langsgaan

Wil je dezelfde taak in elke omgeving uitvoeren, log dan één keer in, haal de omgevingen op en vraag per omgeving een token op. Dit voorbeeld gebruikt `curl` en `jq`:

```bash
BASIS="https://mijn.cootje.com/api"

# 1. Inloggen: token voor de voorkeursomgeving
TOKEN=$(curl -s -X POST "$BASIS/iam/auth/login" \
  -H "Content-Type: application/json" \
  -H "Accept: text/plain" \
  -d "{\"email\": \"$COOTJE_EMAIL\", \"password\": \"$COOTJE_WACHTWOORD\"}")

# 2. Omgevingen ophalen en per omgeving een token opvragen
curl -s "$BASIS/iam/environments/list" -H "Authorization: Bearer $TOKEN" \
  | jq -r '.[]._id' \
  | while read -r OMGEVING_ID; do
      OMGEVING_TOKEN=$(curl -s "$BASIS/iam/auth/$OMGEVING_ID/token" \
        -H "Authorization: Bearer $TOKEN" \
        -H "Accept: text/plain")

      # 3. Gebruik het token van deze omgeving
      curl -s "$BASIS/iam/auth/userinfo" -H "Authorization: Bearer $OMGEVING_TOKEN" \
        | jq -r '.environmentName'
    done
```

## Tokens geldig houden

Elk token is 10 minuten geldig, ook een token dat je voor een andere omgeving hebt opgevraagd. Verlengen werkt per token: een token dat je verlengt met `POST /iam/auth/refreshtoken` blijft voor dezelfde omgeving gelden.

* Werk je kort in elke omgeving, vraag dan per omgeving een vers token op en gooi het daarna weg.
* Werk je lang in meerdere omgevingen tegelijk, bewaar dan per omgeving het token en verleng elk token apart.

## Voorkeursomgeving instellen

De voorkeursomgeving bepaalt voor welke omgeving je bij het inloggen een token krijgt. Je stelt hem in met `POST /iam/environments/{environmentId}/favorite`:

```bash
curl -X POST "https://mijn.cootje.com/api/iam/environments/665f1c2a9b3e4d0012ab34cd/favorite" \
  -H "Authorization: Bearer JOUW_TOKEN"
```

Het antwoord is `204` als het gelukt is en `400` als de omgeving niet bestaat of het account er niet aan gekoppeld is.
