KEPLIN Docs

API's & GraphQL API-sleutels

API-sleutels

API-sleutels genereren, afbakenen en intrekken — de toegang van externe systemen tot de GraphQL van uw apps.

De externe systemen — een ERP dat klanten synchroniseert, een website die bestellingen aanmaakt, een facturatie-integratie — roepen de GraphQL van de apps aan met een API-sleutel: een geheim dat in de header x-api-key van elk verzoek meegaat. De sleutels worden op het niveau van het platform beheerd en zijn gedeeld tussen apps: elke sleutel heeft een scope — u kiest de apps en, per app, alle endpoints of slechts enkele. Een facturatie-integratie kan bijvoorbeeld accounts lezen in de app Klantenbeheer en documenten schrijven in een andere app, met één enkele sleutel.

Nota

De sleutels horen bij wie het platform beheert: de pagina API-sleutels is alleen beschikbaar voor beheerdersaccounts.

De pagina API-sleutels

Open het menu API-sleutels in de globale navigatie. De lijst toont alle sleutels van het platform:

Kolom Wat het is
Naam De naam die u de sleutel gegeven hebt — die identificeert de integratie.
Prefix De eerste tekens van de sleutel (bijv. amk_A1b2C3…) — daarmee herkent u welke welke is zonder ooit de hele sleutel te tonen.
Scope De apps waartoe hij toegang geeft en, per app, "alle endpoints" of de lijst van de toegekende.
Status actief of ingetrokken.
Laatst gebruikt Wanneer de sleutel voor het laatst gebruikt is — nooit, als dat nog niet gebeurd is.

De pagina API-sleutels, met de scope en het laatste gebruik van elke sleutel.
De pagina API-sleutels, met de scope en het laatste gebruik van elke sleutel.

Dica

De kolom Laatst gebruikt is uw opruimgereedschap: een sleutel die maandenlang ongebruikt is, is kandidaat om ingetrokken te worden.

Een API-sleutel aanmaken

  1. Klik op Nieuwe API-sleutel.
  2. Geef een Naam van de sleutel — bijv. facturatie-integratie.
  3. Vink bij Scope — toegestane apps en endpoints de apps aan die u wilt opnemen. Standaard geeft elke aangevinkte app "Alle endpoints van deze app."
  4. Om de toegang in een app aan te scherpen, vinkt u Beperken tot specifieke endpoints aan en kiest u de API's stuk voor stuk. Bij een Tabel-API dekt de toekenning alle actieve bewerkingen — de lijst toont "geeft toegang tot: getContas, addContas, …" zodat u precies weet wat u toekent.
  5. Klik op API-sleutel genereren.

Het aanmaakvenster van een API-sleutel, met de scope per app en endpoint.
Het aanmaakvenster van een API-sleutel, met de scope per app en endpoint.

De sleutel kopiëren en bewaren

Na het genereren toont het venster de Sleutel in leesbare tekst — één enkele keer. Kopieer hem met Kopiëren en bewaar hem op een veilige plek (een geheimenbeheerder, de kluis van uw team). Zodra u het venster sluit, ziet u hem niet meer terug — het platform bewaart de sleutel niet in leesbare vorm; raakt u hem kwijt, dan kunt u hem alleen intrekken en een nieuwe genereren.

De gegenereerde sleutel, in leesbare tekst voor de enige keer, met de knop Kopiëren.
De gegenereerde sleutel, in leesbare tekst voor de enige keer, met de knop Kopiëren.

Atenção

Behandel de sleutel als een wachtwoord: zet hem niet in broncode, niet in URL's en niet op gebruikersschermen. Vermoedt u een lek, trek hem dan meteen in — een nieuwe sleutel genereren kost seconden.

De sleutel gebruiken

De sleutel gaat mee in de header x-api-key van elk verzoek aan het GraphQL-endpoint van de app:

curl -X POST 'https://uw-host/api/graphql/gestao-clientes' \
  -H 'content-type: application/json' \
  -H 'x-api-key: amk_………' \
  -d '{"query":"query { getContas(take: 5) { id nome } }"}'

Het tabblad Docs van elke API genereert dit voorbeeld (en de JavaScript-variant) al met de juiste bewerking — alleen uw sleutel ontbreekt nog.

Wat een sleutel wel en niet ziet:

  • Alleen gepubliceerde API's — concepten nooit, ook niet met de scope van een hele app.
  • Alleen wat de scope toekent: een app buiten de scope aanroepen geeft 403 — API key not authorised for this project; een endpoint buiten de scope aanroepen, 403 — API key not authorised for this endpoint.
  • Altijd de hoofdversie van de app (of de gepubliceerde versie van het gebruikte adres) — nooit de werkversie van een developer.

Limieten en fouten

Elke sleutel heeft een plafond aan verzoeken per minuut. De foutantwoorden die een integratie moet kunnen afhandelen:

Antwoord Betekenis Wat te doen
401 Sleutel ontbreekt, is ongeldig, verlopen of ingetrokken. Controleer de header en de status van de sleutel in de lijst.
403 Sleutel is geldig maar heeft geen toegang tot de app of het endpoint. Pas de scope aan — genereer een nieuwe sleutel met de juiste scope.
429 Het plafond aan verzoeken per minuut is bereikt. Wacht de tijd af die in de header retry-after staat en probeer opnieuw.

Een sleutel intrekken

  1. Klik in de lijst op het intrekpictogram van de regel.
  2. Bevestig met Sleutel intrekken.

Het intrekken is onmiddellijk: alle apps die deze sleutel gebruiken, verliezen bij het volgende verzoek toegang. Een ingetrokken sleutel kan niet opnieuw worden geactiveerd — hij blijft in de lijst staan, gemarkeerd als ingetrokken, als registratie.

Waarom niet…?

  • Ik ben de sleutel kwijt — kan ik hem nog eens zien? Nee. De leesbare sleutel wordt alleen op het moment van aanmaken getoond. Trek de oude in en genereer een nieuwe.
  • Ik moet toegang geven tot nog een endpoint — bewerk ik de sleutel? De scope bepaalt u bij het aanmaken. Genereer een nieuwe sleutel met de volledige scope, wissel hem in de integratie om en trek de oude in.
  • Waarom krijgt de integratie 403 op een nieuw endpoint? De sleutel is beperkt tot specifieke endpoints en het nieuwe staat niet in de lijst — hetzelfde geneesmiddel: een nieuwe sleutel met de juiste scope.
  • Geeft de sleutel toegang tot de schermen van de app? Nee. Een sleutel praat alleen met het GraphQL-endpoint. De gebruikersaccounts van de app zijn iets anders, en worden in de instellingen van de app zelf beheerd.