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

# Configuratie

Voordat je integratie de Engyon API kan aanroepen, moet een beheerder van je auditororganisatie een **service account** aanmaken en de credentials veilig met je delen.

Een service account is een machine-identiteit voor je integratie. Het kan niet inloggen via de Engyon-browserinterface. In plaats daarvan authenticeert het met een `client_id` en `client_secret` via de OAuth 2.0 client credentials-flow die in Basis wordt beschreven.

### Wie kan een service account aanmaken

Service accounts worden beheerd vanaf de organisatiepagina in Engyon. Je hebt rechten nodig om de organisatie bij te werken (doorgaans een organisatieadmin).

### Een service account aanmaken

1. Log in op Engyon via <https://audit.engyon.io>.
2. Open **Opties** (linksonder) en ga naar **Organisatie**.
3. Open het tabblad **Service accounts**.
4. Klik op **+ Service account** om het aanmaakformulier te openen.
5. Vul een duidelijke **naam** in die het doel van de integratie aangeeft (bijvoorbeeld `CRM-integratie` of `Practice management-sync`).
6. Vul optioneel een **beschrijving** in.
7. Selecteer één of meer **rollen** voor het service account (zie Rollen hieronder).
8. Klik op **Creëer**.

<figure><img src="/files/94W0hLq9fvrNcEJhqOkX" alt=""><figcaption></figcaption></figure>

Na het aanmaken toont Engyon eenmalig de **client id** en **client secret**.

{% hint style="danger" %}
Kopieer beide waarden meteen en bewaar ze in een secrets manager of een andere veilige locatie. De client secret wordt **niet opnieuw getoond**. Raak je die kwijt, dan moet je een nieuwe secret genereren, waardoor alle bestaande tokens voor dat service account ongeldig worden.
{% endhint %}

<figure><img src="/files/zAF8qzHMFVzhCPAoMIhX" alt=""><figcaption></figcaption></figure>

### Rollen

Rollen bepalen wat het service account mag doen. Engyon biedt momenteel twee API-rollen. Je kunt er één of beide toewijzen, afhankelijk van wat je integratie nodig heeft.

| Rol                     | Technische naam       | Waarvoor                                                                                                                                                |
| ----------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API account manager** | `api_account_manager` | Klanten, juridische entiteiten, audits en gebruikers toewijzen. Koppelt entiteitsaudits aan component audits.                                           |
| **API audit manager**   | `api_audit_manager`   | Werken binnen bestaande audits: auditgegevens lezen, bestanden en source records beheren, scope bijwerken en vergelijkbare handelingen binnen de audit. |

#### Wat elke rol mag

Een service account hoort altijd bij één auditororganisatie. Binnen die organisatie gelden de geselecteerde rollen voor de klanten en audits van dat kantoor. Je integratie heeft geen toegang tot gegevens van andere auditororganisaties.

**API account manager**

Gebruik deze rol wanneer je integratie structuur in Engyon opzet. Deze rol kan onder andere:

* **Klantorganisaties** aanmaken, weergeven en bijwerken
* **Juridische entiteiten** aanmaken, weergeven, bijwerken en verwijderen
* **Audits** aanmaken, weergeven en lezen
* **Component audits** (controle-eenheden) binnen een groepsdossier aanmaken en beheren
* Gebruikers toewijzen aan klantorganisaties en audits
* Een entiteitsaudit koppelen aan component audits (een auditnetwerk opbouwen)
* Credit-gerelateerde informatie lezen die nodig is voor het aanmaken van audits

**API audit manager**

Gebruik deze rol wanneer je integratie werkt met de inhoud van audits die al bestaan. Deze rol kan onder andere:

* Auditdetails, toegewezen gebruikers en scope lezen
* **Bestanden** en gerelateerde goedkeuringen aanmaken en beheren
* **Source records** aanmaken en beheren
* **Risico’s** lezen en aanmaken
* **Controles** (checks) lezen en bedragen bijwerken
* **Component audits** aanmaken en beheren
* Acties rond documentverzoeken uitvoeren die via de API beschikbaar zijn

{% hint style="success" %}
Voor de meeste end-to-end integraties (klanten en audits aanmaken, en daarna auditgegevens pushen of ophalen) wijs je **beide** rollen toe aan het service account.
{% endhint %}

### Een bestaand service account beheren

Vanaf het tabblad **Service accounts** kun je:

* **Bewerken** van naam, beschrijving en rollen
* **Secret opnieuw genereren** — maakt een nieuwe client secret aan en maakt alle bestaande access tokens voor dat service account meteen ongeldig
* **Verwijderen** van het service account — verwijdert de credentials, de onderliggende service account-gebruiker en de roltoewijzingen. Dit kan niet ongedaan worden gemaakt.

{% hint style="warning" %}
Het opnieuw genereren van de secret is de juiste actie wanneer een secret mogelijk is gelekt. Stem dit af met je integratieteam voordat je opnieuw genereert, omdat de integratie stopt met authenticeren totdat die is bijgewerkt met de nieuwe secret.
{% endhint %}

### Checklist voordat je de API gaat aanroepen

* [ ] Er bestaat een service account voor je integratie
* [ ] De juiste rollen zijn toegewezen (`api_account_manager`, `api_audit_manager`, of beide)
* [ ] Je hebt de `client_id` en `client_secret` veilig opgeslagen
* [ ] Je weet welke omgeving je aanroept (`https://audit.engyon.io`)

Ga verder met \[Basishandelingen]\(<https://engyon.gitbook.io/engyon/api/basishandelingen>) om een access token op te halen en je eerste geauthenticeerde request te doen.