> For the complete documentation index, see [llms.txt](https://docs.cerrix.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cerrix.com/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-key-management-and-setup.md).
# API-sleutelbeheer en -instelling
Deze handleiding legt uit hoe u API-sleutels kunt genereren en configureren voor het koppelen van externe toepassingen aan de CERRIX API's. De CERRIX API-handleidingen beschrijven beschikbare endpoints en payload-indelingen. Deze handleiding richt zich op de **de stappen die nodig zijn om API-referenties veilig aan te maken en te beheren**.
## **1. Maak een nieuwe API-sleutel aan**
1. Log in bij CERRIX.
2. Klik rechtsboven op uw **naam**.
3. Selecteer **Profiel bekijken**.\
4. Ga in het linkermenu naar **API-sleutels**.
5. Klik op **Toevoegen** om een nieuwe API-sleutel aan te maken.\
6. Voer een beschrijvende **Naam** voor de API-sleutel in.
7. Het **vervaldatum** van een API-sleutel kan worden ingesteld, maar er is een maximumlimiet: deze **kan niet op langer dan één jaar worden ingesteld** vanaf de aanmaakdatum. U kunt deze periode indien gewenst verkorten, maar niet verlengen tot voorbij het maximum van één jaar.
## **2. Configureer toegestane IP-adressen**
Om de beveiliging te verbeteren, kunnen API-sleutels worden beperkt tot specifieke IP-adressen.
1. Onder **Toegestane IP-adressen**, klik op **Toevoegen**.
2. Voer het IP-adres in van de server of het systeem dat deze API-sleutel gaat gebruiken.
* Dit is doorgaans het IP-adres van het systeem waarop uw integratie of toepassing draait.
* Voor testdoeleinden kunt u ook uw eigen IP-adres gebruiken. *(Bevestig met uw beheerder welk IP-adres geschikt is.)*
## **3. Selecteer toegankelijke API's**
Bij het aanmaken van een API-sleutel kunt u bepalen welke API's de sleutel mag aanroepen.
1. Selecteer in het configuratiescherm van de API-sleutel de API's waartoe u deze sleutel toegang wilt geven.
2. Alleen de geselecteerde API's zijn met deze sleutel toegankelijk. Hierdoor kunt u het principe van minimale rechten volgen.
## **4. Sla de inloggegevens op en haal ze op**
1. Klik op **Opslaan** om de API-sleutel aan te maken.
2. Zodra u hebt opgeslagen, genereert het systeem:
* **Identifier**
* **Wachtwoord**
{% hint style="warning" %}
**Belangrijk:** Dit is de **enige keer** dat deze gegevens worden weergegeven. Om veiligheidsredenen kunnen ze later niet meer worden opgehaald.
* Kopieer de Identifier en het wachtwoord onmiddellijk.
* Bewaar ze veilig in uw integratietoepassing of in een veilige wachtwoordbeheerder.
Als u de gegevens kwijtraakt, moet u een nieuwe API-sleutel genereren.
{% endhint %}
## **5. De API-sleutel gebruiken**
Gebruik de gegenereerde **Identifier** en **Wachtwoord** om uw verzoeken te authenticeren zoals beschreven in de [CERRIX API-handleidingen](/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-documentation.md). Zorg ervoor dat:
* Het IP-adres van het aanroepende systeem overeenkomt met een van de toegestane IP-adressen.
* De API-sleutel toegang heeft gekregen tot de endpoints die u wilt aanroepen.
## Vereiste rol en waar API-sleutels worden aangemaakt
Het beheren van API-sleutels vereist de **Applicatiebeheerder** rol.
API-sleutels worden altijd aangemaakt vanuit uw eigen gebruikersprofiel — klik rechtsboven op uw **naam** rechtsboven, kies **Profiel bekijken**en open **API-sleutels**. Ze zijn **niet** beheerd via User Management, en elke sleutel behoort tot het profiel dat deze heeft aangemaakt.
## Toegang tot DirectData-eindpunten
De DirectData-eindpunten (bijvoorbeeld de General-, Risico-, Beheersmaatregel- en BIM DirectData-datasets) retourneren **alle gegevens die aanwezig zijn in de CERRIX-omgeving, zonder filtering op rollen of machtigingen**. In tegenstelling tot de applicatie zelf wordt de uitvoer niet beperkt tot de organisaties of modulerollen van de aanroepende gebruiker.
Omdat het antwoord altijd de volledige dataset bevat, kunnen de DirectData-eindpunten alleen worden aangeroepen met een API-sleutel die toebehoort aan een gebruiker met de **Applicatiebeheerder** rol. Er is geen rol met lagere bevoegdheden of machtigingsset die toegang tot DirectData verleent.
Op de API-sleutel zelf wordt DirectData-toegang beheerd met één enkele instelling: **DirectData ophalen**, vermeld onder **Algemene API's → Data-API's** in de sleutelconfiguratie. Door deze in te schakelen krijgt de sleutel toegang tot de DirectData-eindpunten van **alle modules** — DirectData-toegang kan niet worden beperkt tot afzonderlijke modules.
Beperk voor een rapportage-integratie die DirectData leest de voetafdruk van het account zoveel mogelijk:
* Gebruik liever een toegewijd serviceaccount dan een persoonlijk account (zie *Serviceaccounts en automatisering* hieronder).
* Schakel **DirectData ophalen** alleen in op sleutels die door de rapportage-integratie worden gebruikt, en laat API's die de integratie niet nodig heeft niet geselecteerd.
* Beperk de sleutel tot de IP-adressen van de integratieserver en houd de vervalperiode kort.
## Serviceaccounts en automatisering
CERRIX authenticeert API-aanroepen met een **API-sleutel (Identifier + wachtwoord)** die gekoppeld is aan een gebruikersprofiel. Er wordt geen apart client-ID/client-secretmodel gebruikt, dus er is geen afzonderlijk 'applicatie'-inloggegeven dat losstaat van een gebruiker.
Voor integraties zonder toezicht (bijvoorbeeld een Power BI-extract of een taakautomatiseringsbot) is het aanbevolen patroon:
1. Maak een normaal CERRIX-gebruikersaccount aan, bij voorkeur gekoppeld aan een **gedeelde teaminbox** in plaats van de mailbox van één individu.
2. Geef dat account alleen de bevoegdheden die de integratie nodig heeft.
3. Maak de API-sleutel aan onder dat account.
Omdat de sleutel gekoppeld is aan een niet-persoonlijk account, wordt deze centraal beheerd en blijft hij werken wanneer individuele personeelsleden veranderen.
{% hint style="info" %}
Er kan een gebruiker zonder e-mailadres worden aangemaakt, maar een **API-sleutel kan niet voor zo'n gebruiker worden aangemaakt** — het account heeft een mailbox nodig. Een softwarerobot (RPA-bot) kan onder dezelfde regels een eigen account en sleutel krijgen, afhankelijk van de beschikbare eindpunten (er is momenteel bijvoorbeeld geen API voor het aanmaken van testplannen).
{% endhint %}
## Een sleutel overdragen wanneer de eigenaar vertrekt
API-sleutels zijn gebonden aan een individueel gebruikersprofiel. Ze **kunnen niet opnieuw worden toegewezen** aan een andere gebruiker, en de inloggegevens worden slechts één keer getoond bij het aanmaken, dus een bestaande sleutel kan niet worden overgedragen.
Wanneer de eigenaar van een sleutel de Organisatie verlaat, moet de opvolger:
1. Maak een **nieuwe sleutel aan onder hun eigen profiel** (rechtsboven → Profiel bekijken → API-sleutels).
2. Configureer deze met de **zelfde toegestane IP's en machtigingen voor eindpunten**en stel een vervaldatum in (maximaal één jaar).
3. Gebruik beide sleutels **naast elkaar** tijdens de overgang, en trek vervolgens de oude sleutel in zodra de integratie de nieuwe gebruikt.
## Rollen en schrijf- (POST-)eindpunten
De API-machtigingen die u op een API-sleutel selecteert, dekken de leesbewerkingen van de modules waartoe ze behoren. Schrijfbewerkingen — bijvoorbeeld `POST /taskdata/v1/tasks`, `POST /taskdata/v1/tasks/{guid}` en `POST /taskdata/v1/tasks/{guid}/add/document`, gebruikt om voorbeelden te uploaden en taken aan te maken voor bewijsuploaders, testers en beoordelaars — worden niet aangeboden als afzonderlijk selecteerbare machtigingen op de sleutel.
Deze aanroepen worden gedaan met een API-sleutel die toebehoort aan een gebruiker met de **Applicatiebeheerder** rol. Net als bij de hierboven beschreven DirectData-eindpunten is er momenteel geen rol met lagere rechten die toegang verleent tot de schrijf-eindpunten.
Wanneer u zo'n integratie instelt, houd de voetafdruk van het account zo klein mogelijk:
* Maak een **speciaal serviceaccount** voor de integratie in plaats van een persoonlijk account (zie *Serviceaccounts en automatisering* hierboven), en reserveer het alleen voor de integratie.
* Beperk de sleutel tot de **IP-adressen van de integratieserver**en stel een vervaldatum in (maximaal één jaar).
* Verleen de sleutel alleen de API-machtigingen die de integratie daadwerkelijk gebruikt, en roteer deze volgens een vast schema.
{% hint style="info" %}
Het kunnen verlenen van API-schrijftoegang zonder de volledige rol Application Administrator is een erkende wens. Als uw integratie dit nodig heeft, dien dan een idee in of stem erop in de [CERRIX Community](https://community.cerrix.com) — de vraag van klanten bepaalt de prioritering — en laat CERRIX-support weten wat uw gebruiksscenario is, zodat we u intussen kunnen adviseren over de beste opzet.
{% endhint %}
## Problemen met API-verbindingen oplossen
Gebruik de onderstaande controles wanneer een API-verbinding mislukt.
{% hint style="warning" %}
Deel nooit een volledige `Autorisatie` header of uw API-inloggegevens in een supportticket of e-mail. Als inloggegevens zijn blootgesteld, genereer dan de sleutel opnieuw.
{% endhint %}
**Acceptatie en productie zijn afzonderlijke omgevingen, elk met hun eigen sleutels.** Een sleutel die op acceptatie is aangemaakt, is niet geldig op productie, zelfs niet met identieke code. Maak de sleutel aan terwijl u bent aangemeld bij de omgeving die u wilt aanroepen, en bevestig dat het IP-adres van de aanroeper op de sleutel van die omgeving is toegestaan.
Veelvoorkomende fouten:
* **400 – "Er is geen authenticationScheme opgegeven"**: de aanroep verzendt geen Basic-authenticatie. Controleer of de API-sleutel (Identifier) en het wachtwoord beide zijn opgegeven. Om het probleem te isoleren, test u een ander DirectData-eindpunt zoals `/api/directdata/v1/Risico`.
* **401 Niet-geautoriseerd / "inloggegevens ongeldig" / "de opgegeven inloggegevens voor de webbron zijn ongeldig"**: CERRIX accepteert de sleutel niet langer. De gebruikelijke oorzaken zijn een **verlopen sleutel** (sleutels zijn maximaal één jaar geldig), een sleutel die is ingetrokken of opnieuw aangemaakt, of een wijziging in de toegestane IP-adressen. Houd er rekening mee dat een cloud-BI-vernieuwing vanaf een ander IP-adres kan worden uitgevoerd dan een desktoptool. Controleer uw sleutel via Profiel weergeven → API-sleutels en maak een nieuwe aan als deze verlopen is.
* **Verbindingsfout (bijvoorbeeld bij verbinding maken vanuit Power BI)**: dit is meestal soft-IP-whitelisting. Open de pagina van je profiel **API** pagina, keur het aanroepende IP-adres goed onder **Aangevraagde IP-adressen**, en klik **Opslaan**.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.cerrix.com/cerrix-documentation-nl/cerrix-functionaliteiten/admin-settings/api-key-management-and-setup.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
