Oħloq u kkonfigura ċavetta API
F'din il-paġna
Għaliex toħloq iċ-ċwievet permezz tal-API
Il-ħolqien manwali ta’ ċavetta jieħu tletin sekonda—li huwa preċiżament il-għaliex għandek bżonn l-awtomazzjoni. Peress li hija mgħaġġla, tagħmilha mingħajr ma taħseb: l-ebda konvenzjoni ta’ smijiet, l-ebda limitu ta’ rata, biss wildcard “biex timxi malajr”. Sitt xhur wara, ħadd ma jkun jaf liema ċavetta tagħmel xiex.
L-użu tal-API jfurzak tsemmi, tillimita l-ambitu, u tpoġġi limitu fuq kull ċavetta għax dawn huma parametri tal-iskript. Il-konsistenza tieqaf milli tkun dixxiplina li trid iżżomm u ssir proprjetà tal-kodiċi. Tista’ tawtomatizza l-ħolqien ta’ ċwievet għall-ambjenti tiegħek (dev, staging, production), tapplika ACLs granulari, u tiddefinixxi limiti ta’ rata—kollox fi ħdan l-iskripts tad-deploy jew l-għodod tal-infrastruttura tiegħek.
Endpoint tal-ħolqien
Biex toħloq ċavetta API, ibgħat talba POST lejn l-endpoint li ġej:
POST /auth/teams/{teamId}/api-keys
Korp tat-talba
{
"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"
}
Parametri dettaljati
name (meħtieġ): identifikatur li jinqara għaċ-ċavetta tiegħek. Agħżel isem deskrittiv li jindika l-użu (prod-backend, staging-chatbot, dev-john). Dan l-isem jidher fil-console u fil-logs tal-użu.
acls (meħtieġ): il-lista ta’ permessi mogħtija lil din iċ-ċavetta. Hemm żewġ formati disponibbli:
api-key:endpoint:[endpoint]— jillimita l-endpoints aċċessibbli (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]— jillimita l-mudelli użabbli (grok-4.20-0309-reasoning, grok-4.3, eċċ.)
Il-karattru * jaġixxi bħala wildcard: api-key:endpoint:* jawtorizza l-endpoints kollha, api-key:model:* il-mudelli kollha. Irriżerva dan għall-iżvilupp lokali. Fil-produzzjoni, wildcard ifisser li ċavetta kompromessa tagħti aċċess għal kull ma jista’ jagħmel it-tim tiegħek—inklużi l-aktar mudelli għaljin, li l-applikazzjoni tiegħek qatt ma tista’ tuża.
qps (għażlieni): mistoqsijiet kull sekonda — numru massimu ta’ talbiet kull sekonda.
qpm (għażlieni): mistoqsijiet kull minuta — numru massimu ta’ talbiet kull minuta.
tpm (għażlieni): tokens kull minuta — numru massimu ta’ tokens ipproċessati kull minuta.
expireTime (għażlieni): data ta’ skadenza fil-format ISO 8601. Iċ-ċavetta tiġi diżattivata awtomatikament f’din id-data.
Eżempju sħiħ b’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"
}'
Ir-risposta fiha ċ-ċavetta sigrieta, li qatt mhux se tintwera mill-ġdid. Din ir-regola għandha konsegwenza prattika li trid tanticipa qabel ma tħaddem l-iskript, mhux wara: jekk toħloq iċ-ċwievet f’loop, il-ħażna trid iseħħ fl-istess mument. Ċavetta mitlufa bejn il-ħolqien u r-reġistrazzjoni ma tistax tiġi rkuprata—trid tħassarha u tibda mill-bidu. Iktebha f’vault (Vault, AWS Secrets Manager) minflok fl-output standard tat-terminal tiegħek, fejn tispiċċa fl-istorja tiegħek.
Strateġiji ACL rakkomandati
Ċavetta tal-iżvilupp (wiesgħa)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ideali għall-iżvilupp lokali: l-aċċess huwa wiesa’ għax ma tkunx taf minn qabel x’se tipprova, iżda l-limiti ta’ rata jibqgħu baxxi. Dan huwa l-kompromess it-tajjeb—loop infinit miktub bi żball f’Lejla ta’ Ġimgħa se jiswa ftit ċenteżmi minflok ftit mijiet ta’ ewro.
Ċavetta tal-produzzjoni (ristretta)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
Fil-produzzjoni, ir-regola tinverti: ibda minn dak li l-applikazzjoni fil-fatt tagħmel u awtorizza biss dak. Il-mistoqsija li trid tagħmel meta tikteb l-ACL hija dejjem l-istess—jekk din iċ-ċavetta tnixxi għada, x’jista’ jagħmel parti terza biha? Ċavetta limitata għaċ-chat fuq mudell wieħed u b’limitu ta’ għaxar talbiet kull sekonda tagħti tweġiba qasira.
Ċavetta temporanja (li tiskadi)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
L-iskadenza awtomatika ssolvi l-problema li ħadd ma jimmaniġġja: iċ-ċwievet li n-nies jinsu jħassru. POC, dimostrazzjoni, kuntrattur li jgħaddi—f’dawn il-każijiet kollha, expireTime jiggarantixxi li l-aċċess jitfi waħdu. Din hija l-unika mod affidabbli biex iżżomm inventarju nadif, għax ma tiddependix fuq il-memorja ta’ ħadd.
Endpoints ACL disponibbli
Biex tara l-endpoints li tista’ tuża fl-ACLs, ikkonsulta:
GET /auth/teams/{teamId}/endpoints
L-endpoints disponibbli huma: chat, embed, image, models, sample, tokenize, documents. Din il-lista tista’ tevolvi maż-żmien, allura iċċekkja regolarment.
Punti Ewlenin
- Il-ħolqien taċ-ċavetta iseħħ permezz ta’
POST /auth/teams/{teamId}/api-keys - L-ACLs isegwu l-format
api-key:endpoint:[isem]jewapi-key:model:[isem] - Il-wildcard
*tagħti aċċess sħiħ għall-endpoints jew il-mudelli kollha - Iċ-ċavetta sigrieta tintwera darba biss fil-ħolqien—iffrankaha immedjatament
- Dejjem iddefinixxi limiti ta’ rata (
qps,qpm,tpm) adattati għall-użu - Uża
expireTimegħal ċwievet temporanji