Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Listar e modificar as suas chaves

Aula 3 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Inventário das suas chaves de API
  2. Listar chaves
  3. Modificar uma chave existente
  4. Verificar a propagação
  5. Cenários comuns
  6. Pontos-chave

Inventário das suas chaves de API

Com o tempo, a sua equipa acumula chaves de API para diferentes ambientes, projetos e membros. A Management API permite-lhe listar todas as chaves ativas, filtrar por permissões e modificar as suas definições sem necessidade de as recriar.

Listar chaves

Este endpoint é o ponto de partida para qualquer auditoria de acesso e é frequentemente onde descobre o inventário real: chaves criadas para um teste há oito meses, uma chave em nome de um antigo membro da equipa, duas chaves de produção sem que ninguém saiba qual está em uso. Liste antes de criar qualquer coisa nova; a chave de que precisa pode já existir.

curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Parâmetros do pedido

  • pageSize: número de chaves por página (por predefinição, são devolvidas todas as chaves)
  • paginationToken: token para recuperar a página seguinte se o número de chaves exceder o tamanho da página
  • aclFilters: filtrar chaves por permissões específicas

Filtrar por ACL

Pode recuperar apenas chaves com um determinado nível de acesso:

# Listar apenas chaves com acesso ao chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Esta filtragem é o que torna uma auditoria gestionável para além de uma dúzia de chaves. Duas questões surgem na prática e são respondidas por um único pedido: quem pode chamar o modelo mais dispendioso e quais as chaves que ainda possuem um caráter universal (wildcard). A segunda é a mais útil — um caráter universal esquecido em produção é o erro de configuração mais comum e o mais silencioso.

Paginação

Para equipas com muitas chaves, utilize a paginação:

# Primeira página de 10 chaves
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

# Página seguinte com o token recebido
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Modificar uma chave existente

Modificar em vez de recriar não é apenas uma conveniência: a chave secreta mantém-se inalterada, pelo que não é necessário nenhum deployment. Isto permite-lhe ajustar limites ou restringir permissões sem interrupção do serviço e, em caso de suspeita, reduzir os direitos de uma chave em segundos enquanto prepara a sua rotação.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-backend-v3",
    "acls": [
      "api-key:endpoint:chat",
      "api-key:endpoint:embed",
      "api-key:model:grok-4.20-0309-reasoning"
    ],
    "qps": 30,
    "qpm": 1000,
    "tpm": 3000000
  }'

O que pode modificar

  • name: renomear a chave para refletir uma alteração na utilização
  • acls: adicionar ou remover permissões (endpoints, modelos)
  • qps / qpm / tpm: ajustar os limites de taxa
  • expireTime: prolongar ou encurtar o período de validade

O que não pode modificar

  • O identificador da chave (api_key_id) permanece fixo
  • A chave secreta não se altera durante a modificação (utilize a rotação para esse efeito)
  • A equipa proprietária não pode ser transferida

Verificar a propagação

Eis o detalhe que explica metade dos «bugs» reportados após a modificação de uma chave: a alteração não é instantânea em todos os servidores. Uma chave recém-criada pode devolver um erro 401 durante alguns instantes; uma ACL expandida pode ainda não estar ativa, e procura o erro no seu próprio código quando bastava esperar. O endpoint de propagação existe precisamente para remover esta dúvida:

curl "https://management-api.x.ai/auth/api-keys/$API_KEY_ID/propagation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Este endpoint devolve o estado de propagação da chave. Aguarde que a propagação esteja concluída antes de utilizar a chave em produção, especialmente após modificar ACLs.

Cenários comuns

Atualizar uma chave de desenvolvimento para produção

A passagem para produção é o cenário de modificação mais comum, e o reflexo de criar uma nova chave nesta ocasião é dispendioso: tem de a implementar em todo o lado, atualizar os cofres de senhas (vaults) e a antiga permanece indefinidamente. Aumentar os limites da chave existente evita tudo isto.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "prod-chatbot",
    "qps": 50,
    "qpm": 2000,
    "tpm": 5000000
  }'

Restringir uma chave suspeita de comprometimento

Em caso de suspeita, a ordem das operações é crucial. Restringir primeiro — ACLs vazias, limites de taxa zero — estanca a fuga num único pedido, sem quebrar nada de forma irreversível. A rotação vem depois, offline, assim que tiver identificado onde a chave foi utilizada. O inverso deixa-o com a produção em baixo e uma investigação a conduzir sob pressão.

curl -X PUT "https://management-api.x.ai/auth/api-keys/$API_KEY_ID" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "acls": [],
    "qps": 0,
    "qpm": 0
  }'

Pontos-chave

  • GET /auth/teams/{teamId}/api-keys lista todas as chaves com paginação e filtragem por ACL
  • PUT /auth/api-keys/{apiKeyId} modifica parâmetros sem alterar a chave secreta
  • GET /auth/api-keys/{apiKeyId}/propagation verifica se as alterações estão efetivas
  • Utilize a filtragem por ACL para auditar regularmente o acesso da sua equipa
  • Após qualquer modificação, verifique a propagação antes de utilizar a chave em produção