Skapa och konfigurera en API-nyckel
På denna sida
Varför skapa nycklar via API:t
Att skapa en nyckel manuellt tar trettio sekunder – vilket är exakt varför du behöver automatisera processen. Eftersom det går snabbt gör du det utan att tänka: ingen namnkonvention, inga hastighetsbegränsningar, bara ett jokertecken för att “gå fort”. Sex månader senare vet ingen vad varje nyckel gör.
Genom att använda API:t tvingas du namnge, begränsa behörigheter och sätta tak för varje nyckel eftersom dessa blir skriptparametrar. Konsekvens upphör att vara en disciplin du måste upprätthålla och blir istället en egenskap hos koden. Du kan automatisera skapandet av nycklar för dina miljöer (utveckling, test, produktion), tillämpa granulära åtkomstkontroller (ACL) och definiera hastighetsbegränsningar – allt inom dina distributionsskript eller infrastrukturverktyg.
Skapandepunkt (Endpoint)
För att skapa en API-nyckel skickar du en POST-förfrågan till följande endpoint:
POST /auth/teams/{teamId}/api-keys
Begärandekropp
{
"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"
}
Detaljerade parametrar
name (obligatoriskt): en läsbar identifierare för din nyckel. Välj ett beskrivande namn som indikerar användningsområdet (prod-backend, staging-chatbot, dev-john). Detta namn visas i konsolen och i användningsloggar.
acls (obligatoriskt): listan över behörigheter som beviljas denna nyckel. Två format finns tillgängliga:
api-key:endpoint:[endpoint]– begränsar vilka endpoints som är tillgängliga (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]– begränsar vilka modeller som får användas (grok-4.20-0309-reasoning, grok-4.3, etc.)
Tecknet * fungerar som ett jokertecken: api-key:endpoint:* auktoriserar alla endpoints, api-key:model:* alla modeller. Reservera detta för lokal utveckling. I produktion innebär ett jokertecken att en komprometterad nyckel ger tillgång till allt ditt team kan göra – inklusive de dyraste modellerna, som din applikation kanske aldrig använder.
qps (valfritt): frågor per sekund – maximalt antal förfrågningar per sekund.
qpm (valfritt): frågor per minut – maximalt antal förfrågningar per minut.
tpm (valfritt): tokens per minut – maximalt antal tokens som bearbetas per minut.
expireTime (valfritt): utgångsdatum i ISO 8601-format. Nyckeln inaktiveras automatiskt vid detta datum.
Komplett exempel med 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"
}'
Svaret innehåller den hemliga nyckeln, som aldrig visas igen. Denna regel har en praktisk konsekvens som du måste förutse innan du kör skriptet, inte efteråt: om du skapar nycklar i en loop måste lagringen ske i samma rörelse. En nyckel som går förlorad mellan skapande och registrering går inte att återställa – du måste radera den och börja om. Skriv den till ett valv (Vault, AWS Secrets Manager) snarare än till din terminals standardutmatning, där den hamnar i din historik.
Rekommenderade ACL-strategier
Utvecklingsnyckel (bred)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Idealiskt för lokal utveckling: åtkomsten är bred eftersom du inte vet i förväg vad du kommer att testa, men hastighetsbegränsningarna hålls låga. Detta är rätt kompromiss – en oavsiktlig oändlig loop skriven en fredagskväll kostar några ören istället för några hundralappar.
Produktionsnyckel (begränsad)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
I produktion vänds regeln: börja med vad applikationen faktiskt gör och auktorisera endast det. Frågan du alltid ska ställa när du skriver ACL:n är densamma – om denna nyckel läcker imorgon, vad kan en tredje part göra med den? En nyckel begränsad till chat på en enda modell och capad vid tio förfrågningar per sekund ger ett kort svar.
Tillfällig nyckel (som löper ut)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Automatisk utgång löser problemet som ingen hanterar: nycklar som folk glömmer att radera. Ett POC, en demonstration, en tillfällig konsult – i alla dessa fall garanterar expireTime att åtkomsten stängs av av sig själv. Detta är det enda pålitliga sättet att upprätthålla en ren inventering, eftersom det inte förlitar sig på någons minne.
Tillgängliga ACL-endpoints
För att se vilka endpoints du kan använda i ACL:er, konsultera:
GET /auth/teams/{teamId}/endpoints
De tillgängliga endpoints är: chat, embed, image, models, sample, tokenize, documents. Denna lista kan utvecklas över tid, så kontrollera den regelbundet.
Viktiga punkter
- Skapande av nycklar sker via
POST /auth/teams/{teamId}/api-keys - ACL:er följer formatet
api-key:endpoint:[namn]ellerapi-key:model:[namn] - Jokertecknet
*ger full åtkomst till alla endpoints eller modeller - Den hemliga nyckeln visas endast en gång vid skapandet – spara den omedelbart
- Definiera alltid hastighetsbegränsningar (
qps,qpm,tpm) anpassade efter användningen - Använd
expireTimeför tillfälliga nycklar