Skip to main content
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.

​
Principales y tokens

Todas las credenciales de API usan el formato de prefijo cog_. Incluye tu token en el encabezado Authorization de cada solicitud:
La distinción clave es como qué principal autentica el token:
  • 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.

​
¿Token de acceso personal o usuario de servicio?

Regla general: si la integración debe seguir funcionando después de que dejes el equipo o cambies de rol, usa un usuario de servicio. Si debe hacer exactamente lo mismo que tú puedes hacer, en tu nombre, usa un PAT.
Los usuarios de servicio son cuentas no asociadas a personas, diseñadas para integraciones de API. Se les pueden asignar permisos específicos mediante RBAC y se pueden agregar a organizaciones de forma independiente de los usuarios humanos.

​
Cómo funciona

  1. Crea un usuario de servicio en Settings > Service users (organización) o Enterprise settings > Service users (Enterprise)
  2. Asigna un rol que controle a qué endpoints puede acceder el usuario de servicio
  3. Genera una clave de API — la clave empieza por cog_ y solo se muestra una vez al crearla
  4. Usa la clave en el encabezado Authorization de cada solicitud a la API

​
Ámbitos de usuarios de servicio

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.

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

​
Tokens de acceso personal

Los tokens de acceso personal (PAT) permiten a los usuarios humanos autenticarse de forma programática con su propia identidad. Cuando usas un PAT, la API te reconoce a ti: tus permisos, tu pertenencia a orgs y tu registro de auditoría. Esto resulta útil cuando quieres hacer llamadas a la API en tu propio nombre (p. ej., scripts personales, herramientas locales) en lugar de hacerlo mediante un usuario de servicio compartido. Un PAT no está limitado a una organización ni a una cuenta Enterprise. Te pertenece dentro de tu cuenta y funciona en todas las organizaciones a las que tienes acceso. Cada solicitud especifica una organización en la URL, y tu rol en esa organización determina lo que puede hacer la solicitud. Para las cuentas Enterprise, los PAT se rigen por una política a nivel Enterprise (deshabilitada de forma predeterminada) que los Admin de Enterprise configuran, incluido un flujo de aprobación y la expiración obligatoria de los tokens. Para obtener más información, consulta Tokens de acceso personal.

​
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.
Las API keys 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. Dónde generarla: Settings > API Keys

​
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
  • Usar una API key heredada (apk_ / apk_user_) con Devin MCP: solo se admiten las claves con prefijo cog_
Solución: Verifica que tu API key sea correcta y esté correctamente formateada en el encabezado Authorization. Para usar MCP, asegúrate de usar una clave de API de usuario de servicio (no una clave heredada).

​
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