Devin ofrece varias versiones de API con distintos mecanismos de autenticación y modelos de autorización. Saber qué tipo de API key usar es crucial para una integración adecuada.
Resumen de versiones de la API
| Versión | Autenticación | Modelo de autorización |
|---|
| v1 | API Keys personales o de servicio | Ámbito de organización |
| v2 | API Keys personales | Solo administradores de Enterprise |
| v3 (Beta) | Credenciales de usuario de servicio | RBAC completo |
| Tipo de API key | Prefijo | Descripción |
|---|
| Personal API Key | apk_user_ | Claves con alcance usuario-organización que heredan los permisos individuales del usuario |
| Service API Key | apk_ | Claves de servicio con alcance de organización para automatización |
| Service User Credential | cog_ | Credenciales de usuario de servicio a nivel Enterprise/organización con RBAC |
- Ve a Settings > API Keys en cualquier suborganización
- Haz clic en “Generate New API Key”
- Copia y almacena la clave de forma segura (solo se mostrará una vez)
Versiones de la API compatibles:
- v1: Sí: hereda los permisos del usuario a nivel de organización
- v2: Sí: solo para usuarios con rol de administrador de Enterprise
- v3: No: usa credenciales de Service User en su lugar
Casos de uso recomendados:
- Scripts de automatización personales
- Desarrollo y pruebas
- Integraciones específicas por usuario
Consideraciones de seguridad:
- Las claves están limitadas a los permisos del usuario
- Revocar el acceso de un usuario invalida automáticamente sus claves de API
- Las claves deben cambiarse periódicamente
Claves de API de servicio (con alcance de organización)
- v1: Sí: con alcance de organización
- v2: No: no está disponible
- v3: No: usa Service User Credentials en su lugar
Casos de uso recomendados:
- Automatización a nivel de organización
- Pipelines de CI/CD para equipos específicos
- Herramientas compartidas dentro de una suborganización
Credenciales de usuario de servicio (solo v3)
- Navega a Enterprise Settings > Service Users
- Haz clic en “Create Service User”
- Asigna los roles apropiados (Enterprise Admin, Org Admin, Org Member, etc.)
- Genera una API key para el usuario de servicio
Tipos de usuarios de servicio:
- Enterprise Service Users: Pueden acceder a múltiples organizaciones según los roles asignados
- Organization Service Users: Limitados a organizaciones específicas, con roles a nivel de organización
Versiones de API compatibles:
- v1: No - no disponible
- v2: No - no disponible
- v3: Sí - compatibilidad completa con RBAC
Casos de uso recomendados:
- Automatización en producción con permisos granulares
- Flujos de trabajo multiorganización
- Integraciones sensibles al cumplimiento que requieren registros de auditoría
- Integraciones de larga duración con ámbitos de permisos específicos
Consideraciones de seguridad:
- Los usuarios de servicio aparecen en los registros de auditoría por separado de los usuarios humanos
- Los permisos pueden controlarse con precisión mediante RBAC
- Las claves pueden rotarse sin afectar las cuentas de usuarios humanos
- Ideal para el principio de mínimo privilegio
Todas las API de Devin utilizan autenticación mediante token Bearer. Incluye tu API key en el encabezado Authorization:
Authorization: Bearer your_api_key_here
curl -X POST "https://api.devin.ai/v1/sessions" \
-H "Authorization: Bearer YOUR_V1_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"prompt": "Crear un script simple de Python"
}'
curl -X GET "https://api.devin.ai/v2/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V2_ENTERPRISE_ADMIN_KEY"
curl -X GET "https://api.devin.ai/v3beta1/enterprise/organizations" \
-H "Authorization: Bearer YOUR_V3_SERVICE_USER_KEY"
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 v3 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 una versión de la API incorrecta para tu tipo de API key (por ejemplo, una API key personal con v3)
- Estás intentando acceder a recursos fuera de tu ámbito de permisos
Solución:
- Para v2: Asegúrate de tener el rol de Enterprise Admin
- Para v3: Usa una credencial de usuario de servicio con los roles adecuados
- Para 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 que la URL del endpoint coincida con la versión de la API que estás utilizando y que el recurso exista.
