> For the complete documentation index, see [llms.txt](https://docs.artific.nl/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.artific.nl/voor-beheerders/tools/api-toegang.md).

# API-toegang

Je eigen systemen het platform laten aanroepen, met service accounts en API keys.

## Service accounts

Een service account is een account voor software in plaats van voor een mens. Gebruik er een zodra een ander systeem met het platform moet praten: een website, een backofficetoepassing, een geplande taak.

Service accounts staan onder **Gebruikersbeheer → Service accounts**. Ze worden volledig behandeld op [Service accounts](/voor-beheerders/toegang/service-accounts.md), inclusief hoe je er een aanmaakt, hoe het zijn rechten krijgt en hoe je de sleutels beheert.

De kern:

| Onderdeel     | Hoe het werkt                                                                                            |
| ------------- | -------------------------------------------------------------------------------------------------------- |
| Identiteit    | Een automatisch gegenereerd adres. Jij kiest de naam en de beschrijving.                                 |
| Rechten       | Via lidmaatschap van gebruikersgroepen, precies zoals bij een persoon. Voeg het account toe aan groepen. |
| Inloggegevens | Een of meer API keys.                                                                                    |
| Status        | Actief of inactief. Deactiveren blokkeert authenticatie zonder iets te verwijderen.                      |

## API keys

Sleutels maak je aan op het tabblad **Sleutels** van het service account.

| Veld             | Wat het doet                                                      |
| ---------------- | ----------------------------------------------------------------- |
| **API Key-naam** | Geeft de sleutel een label, zodat je weet welk systeem hem heeft. |
| **Vervaldatum**  | Optioneel, tot maximaal een jaar vooruit.                         |

{% hint style="danger" %}
De sleutel wordt **één keer** getoond, op het moment dat je hem aanmaakt. Hij wordt ook naar je apparaat gedownload. Daarna is hij niet meer te achterhalen. Ben je hem kwijt, verwijder hem dan en maak een nieuwe aan.
{% endhint %}

### Verstandig omgaan met sleutels

* **Eén sleutel per systeem dat hem gebruikt.** Moet er iets worden ingetrokken, dan trek je alleen die ene in.
* **Noem sleutels naar het systeem dat ze heeft**, niet naar de datum waarop je ze hebt gemaakt.
* **Stel een vervaldatum in.** Een sleutel die verloopt, is een sleutel die wordt bekeken.
* **Vervang zonder onderbreking**: maak de nieuwe sleutel aan, neem hem in gebruik, controleer of het systeem werkt en verwijder daarna de oude.
* **Deactiveer voordat je verwijdert** als je iets onderzoekt. Het service account deactiveren blokkeert de toegang meteen en is omkeerbaar; verwijderen niet.

## API-documentatie

De knop **API-documentatie bekijken** op het scherm met service accounts opent de naslagdocumentatie voor de API key-service, opgebouwd uit de eigen specificatie, zodat die altijd actueel is.

Op dezelfde pagina staat een **ID Helper**, die nuttiger is dan hij klinkt. De meeste API-aanroepen hebben het identificatienummer van een assistent, een sessie of een tool nodig, en die met de hand opzoeken is bewerkelijk. De helper heeft twee tabbladen:

* **Assistenten**: zoek in je assistenten, kopieer het ID van een assistent, klap er een open om sessie-ID's te vinden.
* **Toolbox**: zoek elementen, kopieer het ID van een tool en bekijk de argumenten, inclusief welke verplicht zijn en wat de standaardwaarden zijn.

Klik op een ID om het te kopiëren.

## Voordat je tegen de API aan bouwt

1. **Maak een apart service account** voor de integratie, geen gedeeld account.
2. **Geef het alleen de groepen die het nodig heeft.** Het erft alles wat die groepen toekennen.
3. **Maak één sleutel aan**, noteer waar hij wordt bewaard en stel een vervaldatum in.
4. **Bewaar de sleutel** in je eigen geheimenbeheer, nooit in broncode.
5. **Leg vast waar hij voor is**, zodat de volgende persoon begrijpt waarom hij bestaat.