Listar y modificar tus claves
En esta página
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-keyslista todas las claves con paginación y filtrado por ACLPUT /auth/api-keys/{apiKeyId}modifica parámetros sin cambiar la clave secretaGET /auth/api-keys/{apiKeyId}/propagationverifica 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