Създаване и конфигуриране на API ключ
На тази страница
Защо да създавате ключове чрез API
Ръчното създаване на ключ отнема тридесет секунди – точно затова се нуждаете от автоматизация. Тъй като процесът е бърз, го извършвате без да се замисляте: липсва конвенция за именуване, няма лимити на заявките, просто използвате джокър, за да „действате бързо“. Шест месеца по-късно никой не знае кой ключ какво прави.
Използването на API Ви принуждава да именувате, обхватите и ограничавате всеки ключ, тъй като те са параметри на скрипта. Съгласуваността престава да бъде дисциплина, която трябва да поддържате, и се превръща в свойство на кода. Можете да автоматизирате създаването на ключове за Вашите среди (dev, staging, production), да прилагате детайлни списъци за контрол на достъпа (ACLs) и да дефинирате лимити на скоростта – всичко това директно във Вашите скриптове за внедряване или инструменти за инфраструктура.
Крайна точка за създаване
За да създадете API ключ, изпратете POST заявка до следната крайна точка:
POST /auth/teams/{teamId}/api-keys
Тяло на заявката
{
"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"
}
Детайлни параметри
name (задължителен): четим идентификатор за Вашия ключ. Изберете описателно име, което указва употребата (prod-backend, staging-chatbot, dev-john). Това име се появява в конзолата и в логовете за употреба.
acls (задължителен): списък с разрешения, предоставени на този ключ. Налични са два формата:
api-key:endpoint:[endpoint]– ограничава достъпните крайни точки (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]– ограничава използваемите модели (grok-4.20-0309-reasoning, grok-4.3 и др.)
Символът * действа като джокер: api-key:endpoint:* разрешава всички крайни точки, api-key:model:* – всички модели. Запазете това за локална разработка. В производствена среда джокерът означава, че компрометиран ключ дава достъп до всичко, което екипът Ви може да прави – включително до най-скъпите модели, които приложението Ви може никога да не използва.
qps (по желание): заявки в секунда – максимален брой заявки за секунда.
qpm (по желание): заявки в минута – максимален брой заявки за минута.
tpm (по желание): токени в минута – максимален брой обработени токени за минута.
expireTime (по желание): дата на изтичане във формат ISO 8601. Ключът ще бъде автоматично деактивиран на тази дата.
Пълен пример с 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"
}'
Отговорът съдържа секретния ключ, който никога повече няма да бъде показан. Това правило има практическо следствие, което трябва да предвидите преди изпълнението на скрипта, а не след него: ако създавате ключове в цикъл, съхранението трябва да се извърши в същото действие. Ключ, загубен между създаването и регистрацията, не може да бъде възстановен – трябва да го изтриете и да започнете отначало. Запишете го в хранилище за тайни (Vault, AWS Secrets Manager), а не в стандартния изход на терминала, където ще остане в историята Ви.
Препоръчителни стратегии за ACL
Ключ за разработка (широк обхват)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Идеален за локална разработка: достъпът е широк, защото не знаете предварително какво ще тествате, но лимитите на скоростта остават ниски. Това е правилният компромис – безкраен цикъл, написан по грешка в петък вечер, ще Ви струва няколко цента, вместо няколкостотин евро.
Продукционен ключ (ограничен)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
В производствена среда правилото се обръща: започнете от това, което приложението действително прави, и разрешете само него. Въпросът, който винаги трябва да си задавате при писането на ACL, е един и същ – ако този ключ изтече утре, какво може да направи трета страна с него? Ключ, ограничен до chat на един модел и капнат на десет заявки в секунда, дава кратък отговор.
Временен ключ (с изтичащ срок)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
Автоматичното изтичане решава проблема, който никой не обработва: ключовете, които хората забравят да изтрият. POC, демонстрация, временен изпълнител – във всички тези случаи expireTime гарантира, че достъпът се изключва сам. Това е единственият надежден начин за поддържане на чист инвентар, защото не разчита на ничия памет.
Налични крайни точки за ACL
За да видите крайните точки, които можете да използвате в ACLs, консултирайте:
GET /auth/teams/{teamId}/endpoints
Наличните крайни точки са: chat, embed, image, models, sample, tokenize, documents. Този списък може да се променя с времето, затова го проверявайте редовно.
Ключови изводи
- Създаването на ключове става чрез
POST /auth/teams/{teamId}/api-keys - ACLs следват формата
api-key:endpoint:[name]илиapi-key:model:[name] - Джокерът
*предоставя пълен достъп до всички крайни точки или модели - Секретният ключ се показва само веднъж при създаване – запазете го незабавно
- Винаги дефинирайте лимити на скоростта (
qps,qpm,tpm), съобразени с употребата - Използвайте
expireTimeза временни ключове