La API de Devin usa un modelo de principal + token. Un principal es quien eres (tu identidad), y un token es la forma de demostrarlo (tu credencial). Comprender esta distinción es clave para elegir el método de autenticación adecuado para tu caso de uso.
| Principal | Token | Descripción |
|---|
| Usuario de servicio (no humano) | Clave de API de usuario de servicio | Para integraciones automatizadas y pipelines de CI/CD |
| Usuario (humano) | Token de acceso personal (PAT) | Para acceso programático humano con tu propia identidad |
cog_. Incluye tu token en el encabezado Authorization de cada solicitud:
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer cog_your_token_here"
- Una clave de API de usuario de servicio autentica como el usuario de servicio — se aplican la identidad, los permisos y la pertenencia a orgs del usuario de servicio.
- Un token de acceso personal autentica como el usuario humano que lo creó — se aplican la identidad, los permisos y la pertenencia a orgs de ese usuario.
Usuarios de servicio (recomendados para la automatización)
- Crea un usuario de servicio en Settings > Service users (organización) o Enterprise settings > Service users (Enterprise)
- Asigna un rol que controle a qué endpoints puede acceder el usuario de servicio
- Genera una clave de API — la clave empieza por
cog_ y solo se muestra una vez al crearla
- Usa la clave en el encabezado
Authorization de cada solicitud a la API
curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
-H "Authorization: Bearer $DEVIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"prompt": "Create a simple Python script"}'
Ámbitos de usuarios de servicio
| Ámbito | Creado en | Acceso a la API | Caso de uso |
|---|
| Organization | Settings > Service users | /v3/organizations/* | Administración de sesiones, Knowledge, playbooks, secretos |
| Enterprise | Enterprise settings > Service users | /v3/enterprise/* + /v3/organizations/* | Administración entre organizaciones, analítica, registros de auditoría, facturación |
Encuentra el ID de tu organización en la página Settings > Service Users.
Atribución de sesiones con create_as_user_id
create_as_user_id al crear una sesión. La sesión aparecerá en la lista de sesiones de ese usuario y contará en su uso.
Esto requiere el permiso ImpersonateOrgSessions en el rol del usuario de servicio.
- Las claves comienzan con
cog_ y se muestran solo una vez al momento de su creación
- Los usuarios de servicio aparecen por separado de los usuarios humanos en los registros de auditoría
- Los permisos se controlan mediante RBAC — asigna únicamente lo que la integración necesita
- Los usuarios de servicio de Enterprise heredan permisos a nivel de organización en todas las organizaciones
Para obtener instrucciones detalladas de configuración, consulta la guía de inicio rápido de Teams o la guía de inicio rápido de Enterprise.
Tokens de acceso personal (beta cerrada)
Los tokens de acceso personal están actualmente en beta cerrada y se habilitan mediante feature flags. Contacta con soporte para obtener acceso. Los PAT no están disponibles para cuentas con SSO/Enterprise.
Autenticación heredada (desaprobada)
Las API keys heredadas están desaprobadas. Usa la API v3 con autenticación de usuario de servicio. Consulta la guía de migración. | Tipo de clave | Prefijo | Se usa con | Descripción |
|---|
| Clave de API personal | apk_user_ | v1, v2 | Vinculada a una cuenta de usuario, hereda los permisos del usuario |
| Clave de API de servicio | apk_ | v1 | Con ámbito de organización, para automatización |
Prácticas recomendadas de seguridad
Nunca compartas API keys en áreas públicamente accesibles, como repositorios de GitHub, código del lado del cliente o registros.
- Almacena las claves de forma segura: Usa variables de entorno o sistemas de gestión de secretos
- Rota las claves con regularidad: Genera claves nuevas y revoca periódicamente las antiguas
- Usa usuarios de servicio para la automatización: Prefiere usuarios de servicio en lugar de claves personales para producción
- Aplica el principio de mínimo privilegio: Concede solo los permisos mínimos necesarios
- Supervisa el uso: Revisa los registros de auditoría para detectar actividad inesperada de la API
- Revoca de inmediato las claves comprometidas: Si se expone una clave, revócala y genera una nueva
Posibles causas:
- API key no válida o caducada
- Falta el encabezado
Authorization
- Formato incorrecto del token Bearer
Solución: Verifica que tu API key sea correcta y esté correctamente formateada en el encabezado Authorization.
Posibles causas:
- La API key no tiene los permisos necesarios
- Estás usando un tipo de API key incorrecto para el endpoint (por ejemplo, una API key heredada con endpoints v3)
- Estás intentando acceder a recursos fuera de tu ámbito de permisos
Solución:
- Asegúrate de que tu usuario de servicio tenga el rol y los permisos correctos
- Para endpoints heredados v2: asegúrate de tener el rol de Enterprise Admin
- Para endpoints heredados v1: verifica que tengas acceso a la organización
Posibles causas:
- URL del endpoint de la API incorrecta
- El recurso no existe o no tienes permiso de acceso
Solución: Verifica la URL del endpoint y que el recurso exista.
