Guías

Autenticación

Cómo funcionan las claves API, cómo limitar su alcance y cómo rotar una sin interrupciones.

Cada solicitud incluye un token bearer en el encabezado Authorization. No existe otro método de autenticación.

bash
curl https://api.trystac.com/v1/chat/completions \
  -H "Authorization: Bearer $STAC_API_KEY"

Una clave ausente, mal formada, inválida o expirada devuelve 401. No existe ningún caso 403: una clave se crea limitada a un solo stack, así que no hay un estado de "clave válida, stack equivocado" que reportar.

Alcance de la clave

Una clave pertenece exactamente a un stack. No puede leer la base de conocimiento de otro stack, no puede cambiar el comportamiento y no puede acceder a la API del panel de control. El radio de impacto de una clave comprometida es un solo stack.

Vencimiento

Las claves pueden expirar. Elige un período al crearla:

expires_atstring | nullOpcionalPredeterminado: null

Marca de tiempo ISO 8601, o null para una clave que nunca expira. Las solicitudes con una clave expirada devuelven 401.

today7d30d90dcustomnone
namestringObligatorio

Etiqueta mostrada en el panel de control. Usa el nombre del consumidor — checkout-service, no clave 3 — para que la revocación posterior no genere dudas.

Las claves de vida corta son la opción correcta para CI y para cualquier cosa que se ejecute en una máquina que no controlas.

Rotación sin interrupciones

  1. Crear el reemplazo

    Un stack acepta múltiples claves activas, así que la nueva funciona antes de que la antigua sea eliminada.

  2. Desplegarla

    Actualiza el secreto y reemplaza tu servicio. Ambas claves son válidas durante el despliegue.

  3. Confirmar que la clave antigua está inactiva

    La página de Uso muestra el último uso por clave. Espera hasta que la clave antigua haya permanecido inactiva durante un ciclo completo de despliegue.

  4. Revocar

    La revocación es inmediata: las solicitudes en curso se completan, las nuevas reciben 401.

Manejo de errores

EstadoCausa
401Sin encabezado Authorization, clave no reconocida o clave pasada su expires_at

El cuerpo de la respuesta es { "detail": "..." }. Consulta Errores para la estructura completa de errores. Un 401 nunca es reintentable: trátalo como un problema de configuración, no como un error transitorio: reintentar con la misma clave falla igual.