Ir al contenido principal
Español— Elegir un idioma
Menú

Listar y modificar tus claves

Lección 3 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Inventario de tus claves de API
  2. Listar claves
  3. Modificar una clave existente
  4. Comprobar la propagación
  5. Escenarios comunes
  6. Puntos clave

Inventario de tus claves de API

Con el tiempo, tu equipo acumula claves de API para distintos entornos, proyectos y miembros del equipo. La Management API te permite listar todas las claves activas, filtrarlas por permisos y modificar su configuración sin necesidad de recrearlas.

Listar claves

Este punto de acceso es el punto de partida para cualquier auditoría de acceso y, a menudo, es donde descubres el inventario real: claves creadas para una prueba hace ocho meses, una clave a nombre de un antiguo miembro del equipo, dos claves de producción sin que nadie sepa cuál está en uso. Lista antes de crear nada nuevo; es posible que la clave que necesitas ya exista.

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

Parámetros de la solicitud

  • pageSize: número de claves por página (por defecto, se devuelven todas las claves)
  • paginationToken: token para recuperar la siguiente página si el número de claves supera el tamaño de página
  • aclFilters: filtrar claves por permisos específicos

Filtrar por ACL

Puedes recuperar solo las claves con un determinado nivel de acceso:

# Listar solo claves con acceso a chat
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?aclFilters=api-key:endpoint:chat" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Este filtrado es lo que hace viable una auditoría cuando hay más de una docena de claves. En la práctica surgen dos preguntas que una única solicitud responde: ¿quién puede llamar al modelo más caro? y ¿qué claves siguen teniendo un comodín? La segunda es la más útil: un comodín olvidado en producción es el error de configuración más común y el más silencioso.

Paginación

Para equipos con muchas claves, utiliza la paginación:

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

# Siguiente página con el token recibido
curl "https://management-api.x.ai/auth/teams/$TEAM_ID/api-keys?pageSize=10&paginationToken=TOKEN_RECU" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Modificar una clave existente

Modificar en lugar de recrear no es solo una comodidad: la clave secreta permanece igual, por lo que no es necesario ningún despliegue. Esto te permite ajustar límites o restringir permisos sin interrupción del servicio y, en caso de sospecha, reducir los derechos de una clave en segundos mientras preparas su rotación.

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
  }'

Qué puedes modificar

  • name: cambiar el nombre de la clave para reflejar un cambio en su uso
  • acls: añadir o quitar permisos (puntos de acceso, modelos)
  • qps / qpm / tpm: ajustar los límites de tasa
  • expireTime: ampliar o acortar el periodo de validez

Qué no puedes modificar

  • El identificador de la clave (api_key_id) permanece fijo
  • La clave secreta no cambia durante la modificación (usa la rotación para eso)
  • El equipo propietario no se puede transferir

Comprobar la propagación

Este es el detalle que explica la mitad de los «errores» reportados tras modificar una clave: el cambio no es instantáneo en todos los servidores. Una clave recién creada podría devolver un 401 durante unos instantes; una ACL ampliada podría no estar activa aún, y buscas el error en tu propio código cuando solo necesitabas esperar. El punto de acceso de propagación existe precisamente para eliminar esta duda:

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

Este punto de acceso devuelve el estado de propagación de la clave. Espera a que la propagación se complete antes de usar la clave en producción, especialmente después de modificar las ACL.

Escenarios comunes

Elevar una clave de desarrollo a producción

Pasar a producción es el escenario de modificación más común, y el reflejo de crear una nueva clave con esta ocasión resulta costoso: tienes que desplegarla en todas partes, actualizar las bóvedas de secretos y la antigua queda ahí indefinidamente. Aumentar los límites de la clave existente evita todo esto.

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 una clave presuntamente comprometida

En caso de sospecha, el orden de las operaciones importa. Restringir primero (ACL vacías, límites de tasa a cero) detiene la fuga en una solicitud, sin romper nada de forma irreversible. La rotación viene después, fuera de línea, una vez que has identificado dónde se usaba la clave. Hacerlo al revés te deja con la producción caída y una investigación que conducting bajo presión.

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
  }'

Puntos clave

  • GET /auth/teams/{teamId}/api-keys lista todas las claves con paginación y filtrado por ACL
  • PUT /auth/api-keys/{apiKeyId} modifica parámetros sin cambiar la clave secreta
  • GET /auth/api-keys/{apiKeyId}/propagation verifica que los cambios sean efectivos
  • Usa el filtrado por ACL para auditar regularmente el acceso de tu equipo
  • Tras cualquier modificación, comprueba la propagación antes de usar la clave en producción