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

Autenticación con token Bearer

Lección 14 de 14 Actualizado el 30 de julio de 2026 Desarrollador
En esta página
  1. Asegura tus llamadas a la API
  2. El esquema Bearer token
  3. Errores de autenticación
  4. Mejores prácticas de seguridad
  5. Detección de fugas
  6. HTTPS obligatorio
  7. Puntos clave
  8. Comprueba tu comprensión

Asegura tus llamadas a la API

Guía de primeros pasos en la documentación de xAI Toda solicitud enviada a la API de xAI debe estar autenticada. La API utiliza el esquema Bearer token, un estándar ampliamente adoptado para las API REST. Esta lección explica cómo funciona este mecanismo y las mejores prácticas para proteger tus claves en producción.

El esquema Bearer token

Como su nombre indica, quien posea («porte») el token puede acceder a la API. Por eso es fundamental proteger tu clave: no existe ninguna comprobación de identidad más allá del propio token.

Formato de la cabecera

Toda solicitud HTTP debe incluir la cabecera Authorization con el prefijo Bearer seguido de tu clave:

Authorization: Bearer xai-your-api-key

Con cURL, quedaría así:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "grok-4.5", "input": "Hello"}'

En Python, los SDK gestionan esta cabecera automáticamente cuando pasas la clave al constructor del cliente.

Errores de autenticación

HTTP 401 Unauthorized

Este error significa que tu clave falta, no es válida o ha sido revocada. Comprueba:

  • Que la variable de entorno XAI_API_KEY esté definida
  • Que la clave empiece por xai-
  • Que la clave no haya sido revocada en la consola

HTTP 403 Forbidden

Tu clave es válida, pero no tiene los permisos necesarios para la acción solicitada. Esto puede ocurrir con restricciones de equipo sobre ciertas operaciones.

Mejores prácticas de seguridad

Nunca expongas una clave en el código

Las claves nunca deben aparecer en texto plano en:

  • Código fuente versionado (Git)
  • Registros de la aplicación (logs)
  • URL o parámetros de consulta
  • Mensajes de error mostrados a los usuarios
  • Incidencias y solicitudes de extracción (pull requests) de GitHub

Usa una bóveda de secretos

En producción, almacena tus claves en un sistema dedicado:

  • AWS Secrets Manager o Parameter Store
  • Google Secret Manager
  • Azure Key Vault
  • HashiCorp Vault
  • Secretos de tu plataforma de CI/CD (GitHub Actions, GitLab CI)

Rotación de claves

Cambia tus claves periódicamente e inmediatamente si sospechas de una fuga:

  1. Crea una nueva clave en la consola de xAI
  2. Actualiza la clave en tu bóveda de secretos
  3. Vuelve a desplegar tu aplicación
  4. Comprueba que todo funciona con la nueva clave
  5. Revoca la clave antigua en la consola

Limita los permisos

Si trabajas en equipo, crea claves separadas para cada servicio y entorno. Si una se ve comprometida, el impacto quedará limitado a un único contexto.

Detección de fugas

El prefijo xai- permite que las herramientas de detección (escaneo de secretos de GitHub, GitGuardian, TruffleHog) identifiquen claves en el código fuente automáticamente. Activa estas herramientas en tus repositorios para recibir alertas inmediatas en caso de exposición accidental.

Si se detecta una clave en un commit público:

  1. Revócala inmediatamente en la consola de xAI
  2. Revisa tu historial de uso en busca de actividad fraudulenta
  3. Crea una nueva clave
  4. Limpia tu historial de Git (o, mejor aún, considera la clave como comprometida y sigue adelante)

HTTPS obligatorio

La API de xAI solo acepta conexiones HTTPS. TLS cifra tus solicitudes en tránsito, incluida la cabecera Authorization. Nunca intentes eludir esta protección: una solicitud HTTP sin cifrar expondría tu clave en la red.

Puntos clave

  • La API utiliza el esquema Bearer token a través de la cabecera Authorization
  • La clave es el único factor de autenticación: protégela como una contraseña
  • Usa una bóveda de secretos en producción y nunca hardcodees una clave
  • Activa la detección de fugas en tus repositorios Git
  • Rota las claves periódicamente y revoca inmediatamente cualquier clave comprometida

Comprueba tu comprensión

Los fundamentos de la API de xAI: una última comprobación antes de empezar a construir.

1. ¿Qué debes hacer con una clave de API nada más crearla?

Respuesta: Guárdala en un lugar seguro (solo se muestra una vez), expónla mediante la variable XAI_API_KEY en lugar de hardcodearla, usa una clave por entorno y pruébala de inmediato con una llamada a /v1/models.

2. ¿Cuál es la URL base y por qué es tan importante?

Respuesta: https://api.x.ai/v1. Es lo que hace posible la compatibilidad con OpenAI: cambiar base_url y la clave es suficiente para redirigir el código existente de OpenAI hacia Grok.

3. ¿Qué SDK puedes usar con Grok?

Respuesta: El SDK nativo de xAI, el SDK de OpenAI (con la base_url de xAI) y el SDK de Vercel AI en el lado de JavaScript, además de cURL para pruebas: el ecosistema es abierto.

4. ¿Cuál es el endpoint principal de generación?

Respuesta: POST /v1/responses, el formato moderno; chat/completions sigue disponible como opción heredada para compatibilidad.

5. ¿Cómo se autentica cada solicitud?

Respuesta: Con la cabecera Authorization: Bearer y la clave xai-…: el esquema estándar Bearer token, igual independientemente del SDK o herramienta.

Una clave asegurada, la URL base, tu elección de SDK, Bearer en todas partes: la base está lista y los siguientes cursos de API se construyen sobre ella.