Criar e configurar uma chave de API
Nesta página
Por que criar chaves via API
Criar uma chave manualmente leva trinta segundos — é exatamente por isso que precisa de automação. Como é rápido, fá-lo sem pensar: sem convenção de nomes, sem limites de taxa, apenas um curinga “para avançar depressa”. Seis meses depois, ninguém sabe para que serve cada chave.
Utilizar a API obriga-o a nomear, delimitar o âmbito e definir um limite para cada chave, pois estes são parâmetros do script. A consistência deixa de ser uma disciplina que tem de manter para se tornar uma propriedade do código. Pode automatizar a criação de chaves para os seus ambientes (dev, staging, produção), aplicar ACLs granulares e definir limites de taxa — tudo dentro dos seus scripts de implementação ou ferramentas de infraestrutura.
Endpoint de criação
Para criar uma chave de API, envie um pedido POST para o seguinte endpoint:
POST /auth/teams/{teamId}/api-keys
Corpo do pedido
{
"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"
}
Parâmetros detalhados
name (obrigatório): um identificador legível para a sua chave. Escolha um nome descritivo que indique a utilização (prod-backend, staging-chatbot, dev-john). Este nome aparece na consola e nos registos de utilização.
acls (obrigatório): a lista de permissões concedidas a esta chave. Estão disponíveis dois formatos:
api-key:endpoint:[endpoint]— restringe os endpoints acessíveis (chat, embed, image, models, sample, tokenize, documents)api-key:model:[model]— restringe os modelos utilizáveis (grok-4.20-0309-reasoning, grok-4.3, etc.)
O caráter * funciona como um curinga: api-key:endpoint:* autoriza todos os endpoints, api-key:model:* todos os modelos. Reserve isto para desenvolvimento local. Em produção, um curinga significa que uma chave comprometida dá acesso a tudo o que a sua equipa pode fazer — incluindo os modelos mais dispendiosos, que a sua aplicação pode nunca utilizar.
qps (opcional): consultas por segundo — número máximo de pedidos por segundo.
qpm (opcional): consultas por minuto — número máximo de pedidos por minuto.
tpm (opcional): tokens por minuto — número máximo de tokens processados por minuto.
expireTime (opcional): data de expiração no formato ISO 8601. A chave será automaticamente desativada nesta data.
Exemplo completo com 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"
}'
A resposta contém a chave secreta, que nunca mais será exibida. Esta regra tem uma consequência prática que precisa de antecipar antes de executar o script, e não depois: se criar chaves num ciclo, o armazenamento deve ocorrer no mesmo movimento. Uma chave perdida entre a criação e o registo não é recuperável — tem de a eliminar e recomeçar. Grave-a num cofre (Vault, AWS Secrets Manager) em vez da saída padrão do seu terminal, onde acabará no seu histórico.
Estratégias de ACL recomendadas
Chave de desenvolvimento (ampla)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"qps": 5,
"qpm": 50
}
Ideal para desenvolvimento local: o acesso é amplo porque não sabe antecipadamente o que vai testar, mas os limites de taxa permanecem baixos. Este é o compromisso certo — um ciclo infinito escrito por engano numa sexta-feira à noite custará alguns cêntimos em vez de algumas centenas de euros.
Chave de produção (restrita)
{
"acls": [
"api-key:endpoint:chat",
"api-key:model:grok-4.20-0309-reasoning"
],
"qps": 50,
"qpm": 2000,
"tpm": 5000000
}
Em produção, a regra inverte-se: parta do que a aplicação faz realmente e autorize apenas isso. A pergunta a fazer ao escrever a ACL é sempre a mesma — se esta chave vazar amanhã, o que pode um terceiro fazer com ela? Uma chave limitada ao chat num único modelo e limitada a dez pedidos por segundo dá uma resposta curta.
Chave temporária (expirável)
{
"acls": ["api-key:endpoint:*", "api-key:model:*"],
"expireTime": "2026-04-10T00:00:00Z"
}
A expiração automática resolve o problema que ninguém gere: as chaves que as pessoas se esquecem de eliminar. Um POC, uma demonstração, um contratante passageiro — em todos estes casos, o expireTime garante que o acesso se desliga sozinho. Esta é a única forma fiável de manter um inventário limpo, porque não depende da memória de ninguém.
Endpoints de ACL disponíveis
Para ver os endpoints que pode utilizar nas ACLs, consulte:
GET /auth/teams/{teamId}/endpoints
Os endpoints disponíveis são: chat, embed, image, models, sample, tokenize, documents. Esta lista pode evoluir ao longo do tempo, por isso verifique regularmente.
Pontos-chave
- A criação de chaves ocorre via
POST /auth/teams/{teamId}/api-keys - As ACLs seguem o formato
api-key:endpoint:[nome]ouapi-key:model:[nome] - O curinga
*concede acesso total a todos os endpoints ou modelos - A chave secreta é exibida apenas uma vez na criação — guarde-a imediatamente
- Defina sempre limites de taxa (
qps,qpm,tpm) adequados à utilização - Utilize
expireTimepara chaves temporárias