Authenticatie
API-sleutels van een account, volledige versus aangepaste toegang, en waar je er een aanmaakt.
Elke aanroep naar CPI bevat een API-sleutel. Er is geen apart client-id, geen OAuth-handshake, geen handtekening om te berekenen: één sleutel, meegestuurd met het verzoek.
Een sleutel aanmaken
Sleutels staan in het dashboard, onder het scherm Ontwikkelaars van het accountmenu, op het
tabblad API-sleutels. Een project heeft een eigen tabblad API dat dezelfde soort sleutel
maakt, al beperkt tot dat project, zodat je nooit met de hand een app_id intypt. De interactieve
sandbox van de API-referentie kan er ook direct een voor je maken, zodat je een
methode kunt proberen voordat je iets in je eigen code aansluit.
Voor het aanmaken van een API-sleutel is identiteitsverificatie nodig, dezelfde controle op niveau 2 die Xuda vraagt voordat een telefoonnummer, een mailbox of een draagbaar IP wordt uitgegeven. Een account zonder verificatie ziet een melding om te verifiëren voordat het sleutelformulier opent.
Bereik: als welk account de sleutel handelt
Een sleutel wordt aangemaakt met een van drie bereiken, en handelt altijd namens het account of de app waarvoor hij is aangemaakt:
- Account: handelt rechtstreeks op je account, zoals je dat vanuit een ingelogde dashboardsessie zou doen. Bereikt elke methode die een gewone accountsleutel kan bereiken.
- App: aangemaakt op het eigen tabblad API van een project, vastgezet op de
app_idvan dat project. - Full Stack VPS: automatisch uitgegeven wanneer je een Full Stack VPS inricht, begrensd door de capaciteitsgroepen die bij het aanmaken zijn gekozen. Zie Full Stack VPS voor wat dat omvat.
Toegang: volledig of aangepast
Elke sleutel kiest ook hoeveel van het publieke oppervlak hij kan bereiken:
- Volledige toegang: alles wat het account via de API kan doen, ook methoden die zijn
toegevoegd na het aanmaken van de sleutel. Privémethoden blijven altijd uitgesloten:
private: trueis een harde muur die bij elke aanroep wordt gecontroleerd, geen standaard die volledige toegang kan overrulen. - Aangepaste toegang: een expliciete toegestane lijst die je opbouwt door methoden aan te
vinken in het sleutelformulier, gegroepeerd per microservice met de velden van elke methode
inline. Een methode die later wordt toegevoegd, is er pas bij als je terugkomt en die toestaat.
Een methode met
clearancepublicis altijd bereikbaar, ook voor een aangepaste sleutel waarbij niets is aangevinkt, omdat een publieke methode geen sessie en geen vermelding in de toegestane lijst nodig heeft.
De methoden die API-sleutels aanmaken, bijwerken en weergeven (create_account_api_key,
get_app_api_keys en de rest van api_module) zijn met een API-sleutel nooit bereikbaar, met
opzet: een referentie kan geen referenties aanmaken of bewerken voor het account waarmee ze
authenticeert. Beheer sleutels vanuit het dashboard of vanuit een ingelogde sessie.
De sleutel meesturen
Via gewone REST is de sleutel één extra verzoekparameter, genaamd api_key: een veld in de
JSON-body bij POST, een queryparameter bij GET. Zie
Een methode aanroepen voor beide vormen.
Via MCP gaat dezelfde sleutel in plaats daarvan in een header Authorization: Bearer, er is geen
veld api_key. Zie MCP.
Een API-sleutel is een bearer-referentie: wie hem heeft, handelt als jouw account. Lever er nooit een mee in clientcode, commit hem niet en plak hem niet in een gedeelde schermafbeelding. Vervang een sleutel meteen als hij ooit op een van die plekken opduikt: vervangen behoudt de naam en de toegangsmodus en trekt de oude waarde in dezelfde stap in.