Saltar al contenido principal
Los usuarios de servicio son cuentas bot dedicadas para el acceso a la API con permisos basados en roles. Este es el método de autenticación recomendado para todas las nuevas integraciones.

​
Cómo funciona

  1. Crea un usuario de servicio en Settings > Service users
  2. Asigna un rol que controle a qué endpoints puede acceder el usuario de servicio
  3. Genera una clave de API (empieza por cog_)
  4. Incluye la clave de API en el encabezado Authorization de cada solicitud
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

ÁmbitoCreado enAcceso a la APICaso de uso
OrganizationSettings > Service users/v3/organizations/*Administración de sesiones, Knowledge, playbooks, secretos
EnterpriseEnterprise 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

Los usuarios de servicio son identidades separadas de los usuarios humanos. De forma predeterminada, las sesiones creadas por un usuario de servicio se atribuyen al propio usuario de servicio. Para crear sesiones en nombre de un usuario específico, pasa el parámetro 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.
¿Estás migrando desde API keys personales? Las API keys personales (v1/v2) creaban sesiones automáticamente como tu propio usuario. Con los usuarios de servicio, usa create_as_user_id para obtener el mismo comportamiento, con RBAC adicional, trazabilidad de auditoría y gestión centralizada de claves. Consulta la Descripción general de la API para ver un ejemplo.

​
Propiedades clave

  • 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.

​
Claves de API heredadas

Las claves de API heredadas se están desaprobando en favor de los usuarios de servicio. Recomendamos migrar las integraciones existentes a usuarios de servicio. Consulta la guía de migración.
Las claves de API heredadas se usan con las API v1 y v2. Siguen funcionando durante el período de desaprobación, pero no son compatibles con funciones nuevas como RBAC, atribución de sesión o paginación basada en cursores.
Tipo de clavePrefijoSe usa conDescripción
Clave de API personalapk_user_v1, v2Vinculada a una cuenta de usuario, hereda los permisos del usuario
Clave de API de servicioapk_v1Con alcance de organización, para automatización
Dónde generarla: Settings > API Keys

​
Autenticación mediante token Bearer

Todas las API de Devin utilizan autenticación mediante token Bearer. Incluye tu clave en el encabezado Authorization: 
Authorization: Bearer your_api_key_here
Esto se aplica tanto a las credenciales de cuentas de servicio como a las API keys heredadas.

​
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.
  1. Almacena las claves de forma segura: Usa variables de entorno o sistemas de gestión de secretos
  2. Rota las claves con regularidad: Genera claves nuevas y revoca periódicamente las antiguas
  3. Usa usuarios de servicio para la automatización: Prefiere usuarios de servicio en lugar de claves personales para producción
  4. Aplica el principio de mínimo privilegio: Concede solo los permisos mínimos necesarios
  5. Supervisa el uso: Revisa los registros de auditoría para detectar actividad inesperada de la API
  6. Revoca de inmediato las claves comprometidas: Si se expone una clave, revócala y genera una nueva

​
Solución de problemas

​
401 No autorizado

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.

​
403 Prohibido

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

​
404 No encontrado

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.

​
Próximos pasos