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

Validar a Chave de Gestão

Aula 13 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Verificar a integridade das suas chaves
  2. Endpoint de validação
  3. Integrar nos seus scripts
  4. Auditoria das chaves de inferência
  5. Lista de verificação de segurança das chaves
  6. Princípio da separação de funções
  7. Pontos-chave

Verificar a integridade das suas chaves

A validação da chave de gestão é a primeira linha de defesa da sua infraestrutura de API. Antes de qualquer operação crítica — implementação, rotação, alterações de faturação — verifique se a sua chave é válida e se as suas permissões estão corretas.

Endpoint de validação

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

A resposta confirma que a chave está ativa e devolve a equipa, as permissões e as datas associadas. Não negligencie a data de expiração: esta é a única informação que lhe permite antecipar uma interrupção em vez de a sofrer, uma vez que uma chave expirada não o avisa — simplesmente devolve um erro 401 na primeira chamada subsequente.

Casos de erro

  • 401 Unauthorized: A chave é inválida, expirou ou foi eliminada
  • 403 Forbidden: A chave é válida, mas não possui as permissões necessárias para a operação solicitada

Integrar nos seus scripts

Verificação no arranque

Validar no arranque desloca a falha para onde ela custa menos. Sem esta verificação, uma chave inválida manifesta-se na primeira chamada útil — ou seja, no meio do processamento, por vezes após vários passos já terem sido executados. Com ela, o script para em três segundos com uma mensagem que identifica a causa.

import requests
import sys

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."

def validate_management_key():
    """Verifica se a chave de gestão é válida."""
    try:
        response = requests.get(
            f"{MANAGEMENT_API}/auth/management-keys/validation",
            headers={"Authorization": f"Bearer {MGMT_KEY}"},
            timeout=10
        )
        if response.status_code == 200:
            print("Chave de gestão válida")
            return True
        elif response.status_code == 401:
            print("ERRO: Chave de gestão inválida ou expirada")
            return False
        else:
            print(f"ERRO: Estado inesperado {response.status_code}")
            return False
    except requests.exceptions.RequestException as e:
        print(f"ERRO DE LIGAÇÃO: {e}")
        return False

if not validate_management_key():
    sys.exit(1)

Verificação periódica de saúde

A verificação periódica de saúde cobre o que a validação no arranque não deteta: serviços de longa duração, iniciados há semanas, cuja chave pode expirar ou ser revogada entretanto. Uma verificação horária é suficiente — o endpoint é leve e não consome tokens de inferência.

#!/bin/bash
# healthcheck-xai.sh — executar a cada hora via cron

STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
  "https://management-api.x.ai/auth/management-keys/validation" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY")

if [ "$STATUS" != "200" ]; then
    echo "ALERTA: Chave de gestão xAI inválida (HTTP $STATUS)"
    # Enviar um alerta (PagerDuty, Slack, email)
fi

Auditoria das chaves de inferência

A auditoria periódica responde a três perguntas que nenhum alerta fará por si: quais as chaves que ainda possuem um wildcard, quais não têm limites de taxa e quais não foram utilizadas há meses. As duas primeiras constituem riscos; a terceira é uma oportunidade de limpeza — e todas três são tratadas numa única passagem.

import requests
from datetime import datetime

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

def audit_api_keys():
    """Audita todas as chaves de API da equipa."""
    response = requests.get(
        f"{MANAGEMENT_API}/auth/teams/{TEAM_ID}/api-keys",
        headers={"Authorization": f"Bearer {MGMT_KEY}"}
    )
    keys = response.json().get("apiKeys", [])

    print(f"=== Auditoria de Chaves de API — {datetime.now().strftime('%d/%m/%Y %H:%M')} ===")
    print(f"Número total de chaves: {len(keys)}")

    for key in keys:
        name = key.get("name", "Sem nome")
        acls = key.get("acls", [])
        expire = key.get("expireTime", "Nunca")
        created = key.get("createdAt", "N/A")

        # Alertas
        warnings = []

        # Chave com acesso wildcard
        if "api-key:endpoint:*" in acls and "api-key:model:*" in acls:
            warnings.append("ACESSO TOTAL (wildcards)")

        # Chave sem expiração
        if expire == "Nunca" or not expire:
            warnings.append("SEM EXPIRAÇÃO")

        # Chave sem limites de taxa
        if not key.get("qps") and not key.get("qpm"):
            warnings.append("SEM LIMITES DE TAXA")

        status = " | ".join(warnings) if warnings else "OK"
        print(f"  [{name}] ACLs: {len(acls)} | Expira: {expire} | {status}")

audit_api_keys()

Lista de verificação de segurança das chaves

Chaves de gestão

As chaves de gestão controlam tudo o resto — o seu comprometimento concede acesso para criar, modificar e eliminar todas as chaves de inferência. Exigem, portanto, o manuseamento mais rigoroso: armazenamento exclusivo num cofre, nunca em texto simples no código ou em configuração versionada; acesso limitado apenas aos administradores de infraestrutura, não aos programadores de aplicações; e validação regular via GET /auth/management-keys/validation, idealmente automatizada como uma verificação de saúde — descobrir uma chave de gestão expirada quando dela precisa urgentemente é o pior cenário operacional.

Chaves de inferência (chaves de API)

Para as chaves de inferência, o princípio orientador é o isolamento: cada aplicação recebe a sua própria chave, nunca uma chave partilhada entre serviços — caso contrário, a rotação de uma chave comprometida quebra todos os serviços de uma vez, e as análises deixam de permitir atribuir o consumo. Cada chave transporta ACLs restritivas calibradas para o seu uso real (sem wildcards em produção), limites de taxa dimensionados para o tráfego esperado e uma data de expiração quando o uso é temporário — um POC destinado a durar duas semanas não precisa de uma chave eterna. A auditoria regular através do script acima fecha o ciclo: revela chaves esquecidas, com privilégios excessivos ou prestes a expirar antes que se tornem problemas.

Princípio da separação de funções

Mantenha uma separação clara entre as chaves:

TipoUtilizaçãoQuem tem acesso
Chave de gestãoAdministração, faturação, análisesAdministradores de infraestrutura
Chave de produçãoChamadas de API em produçãoAplicação de produção
Chave de stagingTestes de pré-produçãoEquipa de desenvolvimento
Chave de desenvolvimentoDesenvolvimento localProgramador individual

Cada chave tem um âmbito definido. Se um programador deixar a equipa, apenas a sua chave de desenvolvimento é eliminada — as outras permanecem intactas.

Pontos-chave

  • GET /auth/management-keys/validation verifica a validade da sua chave de gestão
  • Integre a validação no arranque do seu script e na monitorização
  • Audite regularmente todas as chaves para detetar acessos excessivamente amplos
  • Separe as chaves por ambiente e responsabilidade
  • Emita um alerta imediato perante uma chave inválida (expirada ou eliminada)