Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Oħloq u kkonfigura ċavetta API

Lezzjoni 2 / 14 Aġġornat 29 ta’ Lulju 2026 Zviluppatur
F'din il-paġna
  1. Għaliex toħloq iċ-ċwievet permezz tal-API
  2. Endpoint tal-ħolqien
  3. Eżempju sħiħ b’curl
  4. Strateġiji ACL rakkomandati
  5. Endpoints ACL disponibbli
  6. Punti Ewlenin

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] jew api-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 expireTime għal ċwievet temporanji