Een API-sleutel maken en configureren
Op deze pagina
Waarom u sleutels via de API aanmaakt
Het handmatig aanmaken van een sleutel kost dertig seconden—precies de reden waarom u automatisering nodig heeft. Omdat het snel gaat, doet u het zonder na te denken: geen naamgevingsconventie, geen snelheidslimieten, alleen een wildcard om “snel te werken”. Zes maanden later weet niemand meer wat elke sleutel doet.
Het gebruik van de API dwingt u om elke sleutel een naam te geven, een bereik toe te wijzen en te beperken, omdat dit scriptparameters zijn. Consistentie is niet langer een discipline die u moet handhaven, maar wordt een eigenschap van de code. U kunt het aanmaken van sleutels voor uw omgevingen (ontwikkeling, staging, productie) automatiseren, gedetailleerde toegangscontrolelijsten (ACL’s) toepassen en snelheidslimieten definiëren—allemaal binnen uw implementatiescripts of infrastructuurtools.
Eindpunt voor creatie
Om een API-sleutel aan te maken, stuurt u een POST-verzoek naar het volgende eindpunt:
POST /auth/teams/{teamId}/api-keys
Verzoekbody
{
"name": "ma-cle-production",
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 10,
"qpm": 100,
"tpm": 1000000,
"expireTime": "2026-12-31T23:59:59Z"
}
Gedetailleerde parameters
name (vereist): een leesbare identificatie voor uw sleutel. Kies een beschrijvende naam die het gebruik aangeeft (prod-backend, staging-chatbot, dev-john). Deze naam verschijnt in de console en in de gebruikslogs.
acls (vereist): de lijst met machtigingen die aan deze sleutel zijn verleend. Er zijn twee formaten beschikbaar:
api-key:endpoint:[endpoint]— beperkt de toegankelijke eindpunten (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]— beperkt de bruikbare modellen (grok-4.20-0309-reasoning, grok-4.3, enz.)
Het teken * fungeert als een wildcard: api-key:endpoint:* autoriseert alle eindpunten, api-key:model:* alle modellen. Reserveer dit voor lokale ontwikkeling. In productie betekent een wildcard dat een gecompromitteerde sleutel toegang geeft tot alles wat uw team kan doen—inclusief de duurste modellen, die uw applicatie misschien nooit gebruikt.
qps (optioneel): queries per seconde — maximaal aantal verzoeken per seconde.
qpm (optioneel): queries per minuut — maximaal aantal verzoeken per minuut.
tpm (optioneel): tokens per minuut — maximaal aantal tokens dat per minuut wordt verwerkt.
expireTime (optioneel): vervaldatum in ISO 8601-indeling. De sleutel wordt op deze datum automatisch uitgeschakeld.
Volledig voorbeeld met curl
curl -X POST "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "prod-backend-v2",
"acls": [
"api-key:endpoint:chat",
"api-key:endpoint:embed",
"api-key:model:grok-4.20-0309-reasoning",
"api-key:model:grok-4.3"
],
"qps": 20,
"qpm": 500,
"tpm": 2000000,
"expireTime": "2027-06-30T23:59:59Z"
}'
Het antwoord bevat de geheime sleutel, die nooit meer wordt weergegeven. Deze regel heeft een praktisch gevolg waarop u moet anticiperen voordat u het script uitvoert, niet erna: als u sleutels in een lus aanmaakt, moet de opslag in dezelfde beweging plaatsvinden. Een sleutel die verloren gaat tussen creatie en registratie, is niet herstelbaar—u moet deze verwijderen en opnieuw beginnen. Schrijf deze weg naar een kluis (Vault, AWS Secrets Manager) in plaats van naar de standaarduitvoer van uw terminal, waar deze in uw geschiedenis terechtkomt.
Aanbevolen ACL-strategieën
Ontwikkelingssleutel (breed)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ideaal voor lokale ontwikkeling: de toegang is breed omdat u vooraf niet weet wat u gaat proberen, maar de snelheidslimieten blijven laag. Dit is het juiste compromis—een oneindige lus die per ongeluk op een vrijdagavond is geschreven, kost een paar cent in plaats van een paar honderd euro.
Productiesleutel (beperkt)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
In productie draait de regel om: begin met wat de applicatie daadwerkelijk doet en autoriseer alleen dat. De vraag die u zich bij het schrijven van de ACL altijd moet stellen, is dezelfde: als deze sleutel morgen lekt, wat kan een derde partij er dan mee? Een sleutel die beperkt is tot chat op één enkel model en beperkt tot tien verzoeken per seconde, geeft een kort antwoord.
Tijdelijke sleutel (verloopbaar)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Automatische verloop lost het probleem op dat niemand aanpakt: sleutels die mensen vergeten te verwijderen. Een POC, een demonstratie, een tijdelijke aannemer—in al deze gevallen garandeert expireTime dat de toegang zichzelf uitschakelt. Dit is de enige betrouwbare manier om een schone inventaris te behouden, omdat het niet afhankelijk is van iemands geheugen.
Beschikbare ACL-eindpunten
Om de eindpunten te zien die u in ACL’s kunt gebruiken, raadpleegt u:
GET /auth/teams/{teamId}/endpoints
De beschikbare eindpunten zijn: chat, embed, image, models, sample, tokenize, documents. Deze lijst kan in de loop der tijd evolueren, controleer deze dus regelmatig.
Belangrijkste punten
- Het aanmaken van sleutels gebeurt via
POST /auth/teams/{teamId}/api-keys - ACL’s volgen het formaat
api-key:endpoint:[naam]ofapi-key:model:[naam] - De wildcard
*verleent volledige toegang tot alle eindpunten of modellen - De geheime sleutel wordt slechts één keer bij creatie weergegeven—sla deze direct op
- Definieer altijd snelheidslimieten (
qps,qpm,tpm) die geschikt zijn voor het gebruik - Gebruik
expireTimevoor tijdelijke sleutels