Autenticación y scopes
Autentica solicitudes a la API de AI Glot con claves de espacio de trabajo o tokens de OAuth, elige los scopes mínimos y rota credenciales sin exponer secretos.
Envía una clave de API de espacio de trabajo o un token de acceso OAuth como credencial Bearer:
Authorization: Bearer aig_live_••••••••Nunca incluyas una credencial en una cadena de consulta (query string). Las URL quedan registradas en logs, en el historial del navegador y en las cabeceras Referer.
Claves de API de espacio de trabajo
Los administradores pueden crear claves en Developer tools. El secreto completo solo se muestra una vez; AI Glot únicamente almacena un hash protegido. Puede haber hasta 10 claves activas en un espacio de trabajo.
Utiliza una clave con nombre independiente para cada integración.
Rotar una clave
La lista de claves ofrece la acción Rotar (Rotate). Esta genera una clave de sustitución con el mismo nombre, scopes y fecha de caducidad, y revoca la original en la misma operación. La clave antigua deja de funcionar de inmediato, se marca como replaced en lugar de simplemente revocada y registra qué clave la sucedió.
Esto es deliberado: la rotación se lleva a cabo cuando un secreto puede haberse visto comprometido, y una clave que siga funcionando durante una hora más seguirá activa para quien la haya obtenido. Para una transición planificada y sin tiempo de inactividad, crea una segunda clave, traslada la integración a esta, comprueba que la clave antigua ya no recibe tráfico y, a continuación, revócala.
Tokens de OAuth
La CLI y los clientes MCP compatibles pueden utilizar OAuth 2.1. Se recomienda OAuth para personas físicas porque la conexión registra quién la aprobó y respeta el límite de acceso de dicho miembro. Las claves de API siguen siendo la opción idónea para entornos de CI y servicios backend.
Scopes
Estos son los scopes disponibles actualmente:
| Scope | Permite |
|---|---|
account:read | Identidad del espacio de trabajo, plan, capacidades, límites y resumen de créditos |
usage:read | Totales de uso y desglose por periodos de tiempo |
batches:read | Listar traducciones, consultar el progreso y descargar los resultados completados |
batches:create | Crear una traducción, planificarla y aprobarla. La aprobación consume créditos del espacio de trabajo |
batches:write | Renombrar y archivar traducciones, y cancelar las que estén en curso. La cancelación factura el trabajo ya completado |
glossaries:read | Listar y consultar glosarios |
glossaries:write | Crear, actualizar, sustituir o eliminar glosarios |
Si falta algún scope necesario, se devolverá un error 403 insufficient_scope.
Scopes reservados
Actualmente se pueden conceder dos scopes adicionales, aunque ningún endpoint los procesa todavía. Aparecen en la pantalla de consentimiento de OAuth y en la opción predefinida Acceso completo (Full access) del panel de control, por lo que se documentan aquí en lugar de ocultarse: cualquier permiso cuya aprobación se te solicite debería poder consultarse en la referencia.
| Scope | Permitirá | Estado |
|---|---|---|
files:write | Subir archivos al espacio de trabajo en un paso independiente, en lugar de enviarlos en la llamada de creación | No disponible aún |
webhooks:write | Crear, editar y eliminar los webhooks que notifican a tus sistemas cuando finaliza un trabajo | No disponible aún |
Existen de forma anticipada para que una credencial concedida ahora siga funcionando el día que se lance la funcionalidad, sin necesidad de una segunda ronda de aprobación. Consulta capabilities en GET /v1/account en lugar de los scopes concedidos para determinar qué puede hacer realmente una credencial. Es posible disponer de un scope antes de que exista el endpoint correspondiente.
Límite de acceso de los miembros
Los administradores del espacio de trabajo pueden restringir el acceso de desarrollador de los miembros. Un cliente OAuth recibe la intersección entre lo que ha solicitado y lo que el miembro autorizador tiene permitido utilizar. Volver a conectarse con una solicitud de permisos más amplia no permite eludir un límite de solo lectura.
batches:create está excluido del límite de acceso predeterminado para miembros. Todos los demás scopes se conceden por defecto a la conexión de un miembro; el que consume créditos, no. De lo contrario, un agente que entrara en bucle con una credencial delegada podría consumir la asignación de todo un mes antes de que nadie se percatara, y los créditos no se pueden recuperar. Los administradores del espacio de trabajo amplían este límite de forma deliberada cuando se desea permitir la traducción iniciada por agentes.