> For the complete documentation index, see [llms.txt](https://engyon.gitbook.io/engyon/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://engyon.gitbook.io/engyon/api/basishandelingen.md).

# Basishandelingen

Deze pagina legt uit hoe je authenticeert tegen de Engyon API en hoe je requests in het algemeen uitvoert. Alle voorbeelden gebruiken `curl`, zodat je ze kunt vertalen naar de taal van je keuze.

### Een access token ophalen

De API gebruikt de OAuth 2.0 **client credentials**-grant. Wissel de `client_id` en `client_secret` van je service account in voor een kortlevend access token.

**Endpoint**

```
POST https://audit.engyon.io/api/v1/oauth/token/
```

**Request**

```bash
curl -X POST "https://audit.engyon.io/api/v1/oauth/token/" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET"
```

**Succesvolle response**

```json
{
  "access_token": "........",
  "expires_in": 3600,
  "token_type": "Bearer",
  "scope": "read write"
}
```

| Veld           | Beschrijving                                                             |
| -------------- | ------------------------------------------------------------------------ |
| `access_token` | Het token dat je meestuurt met API-requests                              |
| `expires_in`   | Geldigheidsduur van het token in seconden (momenteel **3600** — één uur) |
| `token_type`   | Altijd `Bearer`                                                          |
| `scope`        | Toegekende scopes                                                        |

{% hint style="info" %}
Vraag een nieuw token aan voordat het huidige verloopt. Hardcode geen tokens in je integratie; haal ze runtime op en cache ze tot kort voor het verlopen.
{% endhint %}

### Een API-request authenticeren

Stuur het access token mee in de `Authorization`-header van elk API-request:

```
Authorization: Bearer YOUR_ACCESS_TOKEN
```

**Voorbeeld — klantorganisaties ophalen**

```bash
curl -X GET "https://audit.engyon.io/api/v1/client-organisations/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

**Voorbeeld — een resource aanmaken (JSON-body)**

```bash
curl -X POST "https://audit.engyon.io/api/v1/client-organisations/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "id": "fictiva-holding",
    "name": "Fictiva Holding",
    "country": "NL",
    "domains": ["fictiva.example"],
    "allow_password_login": false
  }'
```

### Veelvoorkomende responsepatronen

#### Succes

| Status           | Betekenis                                                  |
| ---------------- | ---------------------------------------------------------- |
| `200 OK`         | Het request is geslaagd (lezen of bijwerken)               |
| `201 Created`    | Er is een nieuw resource aangemaakt                        |
| `204 No Content` | Het resource is succesvol verwijderd (waar van toepassing) |

#### Fouten

| Status                  | Betekenis                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------- |
| `400 Bad Request`       | Validatie is mislukt. De body bevat foutmeldingen per veld.                                 |
| `401 Unauthorized`      | Ontbrekend of ongeldig access token. Haal een nieuw token op.                               |
| `402 Payment Required`  | Onvoldoende credits om de audit aan te maken (alleen bij het aanmaken van audits).          |
| `403 Forbidden`         | Het service account heeft niet de vereiste rol/permissie.                                   |
| `404 Not Found`         | Het resource bestaat niet, of is niet toegankelijk voor je auditororganisatie.              |
| `409 Conflict`          | De operatie conflicteert met de huidige staat (bijvoorbeeld de gebruiker is al toegewezen). |
| `429 Too Many Requests` | Je hebt de rate limit overschreden. Wacht en probeer opnieuw (zie Rate limiting).           |

### Paginering

*List*-endpoints geven een gepagineerde envelope terug:

```json
{
  "count": 42,
  "next": "https://audit.engyon.io/api/v1/client-organisations/?page=2",
  "previous": null,
  "results": [
    { "...": "..." }
  ]
}
```

| Queryparameter | Standaard | Beschrijving                                    |
| -------------- | --------- | ----------------------------------------------- |
| `page`         | `1`       | Paginanummer                                    |
| `page_size`    | `20`      | Aantal resultaten per pagina (maximaal **100**) |

**Voorbeeld**

```bash
curl -X GET "https://audit.engyon.io/api/v1/client-organisations/?page=1&page_size=50" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
```

Volg de `next`-URL totdat die `null` is om alle pagina’s op te halen.

### Rate limiting

API-gebruik is rate-limited per service account (`client_id`).

* Standaardlimiet: **1000 requests per uur**
* Bij overschrijding antwoordt de API met `429 Too Many Requests`
* De response bevat een `Retry-After`-header met het aantal seconden dat je moet wachten voordat je opnieuw probeert

Ontwerp je integratie zo dat die `Retry-After` respecteert en onnodige polling vermijdt. Cache referentiegegevens (bijvoorbeeld werkpakketten en industrieën) waar dat zinvol is.

### Organisationscope

Onthoud uit de Introductie:

* De auditororganisatie wordt altijd afgeleid uit het service account.
* Resource-`id`-waarden zijn externe id’s.
* Je kunt alleen gegevens zien en wijzigen die bij je auditororganisatie horen.

### Interactieve documentatie

Voor de volledige lijst van endpoints, request bodies en response-schema’s open je de Swagger UI: <https://audit.engyon.io/api/v1/docs/>

Je moet ingelogd zijn in Engyon om deze pagina te openen. Het ruwe OpenAPI-schema is beschikbaar op <https://audit.engyon.io/api/v1/schema/>.

### Wat nu verder lezen

Ga verder met de \[Use cases]\(<https://engyon.gitbook.io/engyon/api/use-cases>) om concrete flows te implementeren, zoals het aanmaken van een klantorganisatie of een audit.