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

Crear y configurar una clave de API

Lección 2 de 14 Actualizado el 29 de julio de 2026 Desarrollador
En esta página
  1. Por qué crear claves mediante la API
  2. Endpoint de creación
  3. Ejemplo completo con curl
  4. Estrategias de ACL recomendadas
  5. Endpoints de ACL disponibles
  6. Puntos clave

Por qué crear claves mediante la API

Crear una clave manualmente lleva treinta segundos; precisamente por eso necesitas automatización. Al ser tan rápido, lo haces sin pensar: sin convención de nombres, sin límites de tasa, solo un comodín «para ir rápido». Seis meses después, nadie sabe qué hace cada clave.

El uso de la API te obliga a nombrar, delimitar el alcance y establecer un tope para cada clave, ya que estos son parámetros del script. La coherencia deja de ser una disciplina que debes mantener para convertirse en una propiedad del código. Puedes automatizar la creación de claves para tus entornos (desarrollo, preproducción, producción), aplicar listas de control de acceso (ACL) granulares y definir límites de tasa, todo ello dentro de tus scripts de despliegue o herramientas de infraestructura.

Endpoint de creación

Para crear una clave de API, envía una solicitud POST al siguiente endpoint:

POST /auth/teams/{teamId}/api-keys

Cuerpo de la solicitud

{
  "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 detallados

name (obligatorio): un identificador legible para tu clave. Elige un nombre descriptivo que indique el uso (prod-backend, staging-chatbot, dev-john). Este nombre aparece en la consola y en los registros de uso.

acls (obligatorio): la lista de permisos concedidos a esta clave. Hay dos formatos disponibles:

  • api-key:endpoint:[endpoint] — restringe los endpoints accesibles (chat, embed, image, models, sample, tokenize, documents)
  • api-key:model:[model] — restringe los modelos utilizables (grok-4.20-0309-reasoning, grok-4.3, etc.)

El carácter * actúa como comodín: api-key:endpoint:* autoriza todos los endpoints, api-key:model:* todos los modelos. Reserva esto para el desarrollo local. En producción, un comodín significa que una clave comprometida otorga acceso a todo lo que tu equipo puede hacer, incluidos los modelos más costosos que tu aplicación quizás nunca utilice.

qps (opcional): consultas por segundo (queries per second) — número máximo de solicitudes por segundo.

qpm (opcional): consultas por minuto (queries per minute) — número máximo de solicitudes por minuto.

tpm (opcional): tokens por minuto (tokens per minute) — número máximo de tokens procesados por minuto.

expireTime (opcional): fecha de caducidad en formato ISO 8601. La clave se desactivará automáticamente en esta fecha.

Ejemplo completo con 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"
  }'

La respuesta contiene la clave secreta, que nunca volverá a mostrarse. Esta regla tiene una consecuencia práctica que debes anticipar antes de ejecutar el script, no después: si creas claves en un bucle, el almacenamiento debe ocurrir en el mismo movimiento. Una clave perdida entre la creación y el registro no es recuperable; debes eliminarla y empezar de nuevo. Escríbela en una bóveda de secretos (Vault, AWS Secrets Manager) en lugar de a la salida estándar de tu terminal, donde acabará en tu historial.

Estrategias de ACL recomendadas

Clave de desarrollo (amplia)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "qps": 5,
  "qpm": 50
}

Ideal para el desarrollo local: el acceso es amplio porque no sabes de antemano qué vas a probar, pero los límites de tasa se mantienen bajos. Este es el compromiso correcto: un bucle infinito escrito por error un viernes por la noche costará unos céntimos en lugar de unos cientos de euros.

Clave de producción (restringida)

{
  "acls": [
    "api-key:endpoint:chat",
    "api-key:model:grok-4.20-0309-reasoning"
  ],
  "qps": 50,
  "qpm": 2000,
  "tpm": 5000000
}

En producción, la regla se invierte: parte de lo que la aplicación hace realmente y autoriza solo eso. La pregunta que debes hacerte al escribir la ACL es siempre la misma: si esta clave se filtra mañana, ¿qué puede hacer un tercero con ella? Una clave limitada al chat en un único modelo y con un tope de diez solicitudes por segundo da una respuesta breve.

Clave temporal (caducable)

{
  "acls": ["api-key:endpoint:*", "api-key:model:*"],
  "expireTime": "2026-04-10T00:00:00Z"
}

La caducidad automática resuelve el problema que nadie gestiona: las claves que la gente olvida eliminar. Una prueba de concepto, una demostración, un contratista temporal; en todos estos casos, expireTime garantiza que el acceso se desactive por sí solo. Esta es la única forma fiable de mantener un inventario limpio, porque no depende de la memoria de nadie.

Endpoints de ACL disponibles

Para ver los endpoints que puedes usar en las ACL, consulta:

GET /auth/teams/{teamId}/endpoints

Los endpoints disponibles son: chat, embed, image, models, sample, tokenize, documents. Esta lista puede evolucionar con el tiempo, así que compruébala regularmente.

Puntos clave

  • La creación de claves se realiza mediante POST /auth/teams/{teamId}/api-keys
  • Las ACL siguen el formato api-key:endpoint:[nombre] o api-key:model:[nombre]
  • El comodín * otorga acceso total a todos los endpoints o modelos
  • La clave secreta se muestra solo una vez durante la creación; guárdala inmediatamente
  • Define siempre límites de tasa (qps, qpm, tpm) adecuados al uso
  • Usa expireTime para las claves temporales