Skip to main content

​
Resumen general

Los tokens de acceso personal (PAT) permiten a los usuarios humanos autenticarse de forma programática bajo su propia identidad. A diferencia de las API key de usuario de servicio (que autentican como un usuario de servicio no humano), un PAT autentica como tú: el usuario humano que creó el token. Todas las credenciales de API usan el formato de prefijo cog_. Ambos tipos de token se usan de forma idéntica en la cabecera Authorization:

​
Ámbito y permisos

Un PAT te pertenece y está asociado a tu cuenta (tu cuenta de Teams o tu empresa). No está vinculado a una única organización; no existe un «PAT de organización» ni un «PAT de Enterprise». Esto se diferencia de los usuarios de servicio, que se crean a nivel de organización o de Enterprise. Cada solicitud selecciona la organización. Los endpoints de organización la indican en la ruta de la URL (/v3/organizations/{org_id}/...) y la solicitud se autoriza según tu acceso y tu rol en esa organización. Una solicitud para una organización a la que no tengas acceso fallará. El token tiene los mismos permisos que tu usuario. Todo lo que puedas hacer en la aplicación web, podrás hacerlo con tu PAT, y nada más. Para crear, rotar o revocar PATs, necesitas el permiso Gestionar claves de API en la organización cuya configuración estés viendo, o Gestionar claves de API de la cuenta a nivel de cuenta. Este permiso controla quién puede gestionar tokens; no cambia lo que un token puede hacer. Las cuentas de Enterprise también tienen una organización interna que solo almacena Settings a nivel Enterprise. No es un espacio de trabajo. Las solicitudes de PAT dirigidas a ella se rechazan con 403, así que utiliza siempre el ID de una organización secundaria.

​
Cuándo usar PATs

Los PATs están diseñados para situaciones en las que necesitas acceso programático a la API en tu propio nombre:
  • Scripts y herramientas personales — automatiza tus propios flujos de trabajo sin un usuario de servicio compartido
  • Desarrollo local — prueba integraciones con la API usando tu propia cuenta
  • Automatización de corta duración — scripts puntuales que deben atribuirse a ti
Para integraciones de producción, pipelines de CI/CD y automatización compartida, usa claves de API de usuarios de servicio en su lugar. Los usuarios de servicio proporcionan mejores registros de auditoría, gestión centralizada de claves y controles de RBAC. Si no estás seguro de cuál usar, consulta la comparación.

​
Creación y gestión de PAT

Gestiona tus PAT desde la pestaña PAT de la página de Settings de Devin API, en cualquier organización o en Settings de Enterprise. La pestaña muestra los mismos tokens en ambos casos (consulta Ámbito y permisos).
  1. Crea un PAT — asígnale un nombre y una fecha de vencimiento. El token comienza con cog_ y solo se muestra una vez al crearlo.
  2. Usa el token en la cabecera Authorization, igual que una API key de usuario de servicio. Cada llamada a la API se autentica con tu cuenta de usuario: se aplican tus permisos, pertenencia y registro de auditoría.
  3. Rota un PAT — genera un nuevo secreto para un token existente sin cambiar su nombre; el secreto anterior deja de funcionar de inmediato.
  4. Revoca un PAT — invalida el token en cualquier momento.
Los PAT también se aceptan en endpoints en tiempo real, como el WebSocket en vivo de ACP, por lo que herramientas como Devin CLI y los clientes de escritorio pueden autenticarse con un PAT.

​
Gobernanza de Enterprise

En las cuentas Enterprise, la disponibilidad de PAT se controla mediante una política de PAT a nivel Enterprise que se aplica a todas las organizaciones de la Enterprise. Los Admin de Enterprise con Gestionar Settings de Enterprise configuran la política (y gestionan las solicitudes de aprobación) desde la pestaña Políticas de PAT de la página de Settings de Devin API de la Enterprise.

​
Modos de política

​
Política de vencimiento

Cuando se habilitan los PAT para una empresa, todos los PAT deben tener una fecha de vencimiento, limitada por la duración máxima establecida en la política (365 días de forma predeterminada; los Admin pueden configurar un límite menor). Las cuentas no Enterprise (Teams) pueden crear PAT sin fecha de expiración.

​
Flujo de aprobación

En Aprobación requerida:
  1. Un miembro solicita un PAT desde la pestaña PATs (nombre y fecha de vencimiento).
  2. Los Admin de Enterprise ven la solicitud en la Cola de aprobación y la aprueban o rechazan.
  3. Una vez aprobada, el miembro completa la solicitud para generar el token (se muestra una sola vez).
  4. Las solicitudes pendientes vencen automáticamente después de 7 días si no se toma ninguna medida.
Los solicitantes y los administradores reciben notificaciones por correo electrónico en cada etapa del ciclo de vida del token (solicitado, aprobado, rechazado, revocado).

​
Inventario y revocación de tokens

Los Admin de Enterprise con el permiso Gestionar claves de API de la cuenta pueden abrir la vista PAT inventory en la pestaña Políticas de PAT para:
  • Ver los PAT de toda la cuenta Enterprise, con el nombre, el propietario, la fecha de creación, la fecha de vencimiento y el estado de cada token (Active, Revoked o Expired). Filtre por estado o busque por nombre o propietario.
  • Revocar un token activo desde su fila. El inventario solo permite revocar los tokens de uno en uno.
El inventario no indica si un token cumple la política actual. El cumplimiento se comprueba al cambiar la política: si un nuevo modo o un vencimiento máximo más corto hace que algunos tokens existentes dejen de cumplirla, se muestra un diálogo de confirmación con los tokens afectados y sus infracciones antes de aplicar el cambio. Los Admin sin el permiso Gestionar claves de API de la cuenta solo ven el número de tokens afectados. Al confirmar, se revocan esos tokens y se cancelan las solicitudes pendientes de sus propietarios. Si se cambia la política a deshabilitado, se revocan todos los PAT activos y se cancelan todas las solicitudes pendientes.

​
Revocación automática

Los PAT de un usuario se revocan automáticamente cuando pierde su pertenencia a la cuenta, incluso si se elimina mediante el desaprovisionamiento de SCIM o cambios en los grupos del IdP.

​
Consideraciones de seguridad

  • Trata los PAT con el mismo cuidado que las contraseñas: proporcionan acceso completo a tu cuenta
  • Almacena los PAT en variables de entorno o gestores de secretos, nunca en el código fuente
  • Establece el período de expiración más corto que funcione para tu caso de uso
  • Revoca los PAT de inmediato si se ven comprometidos
  • Prefiere las API keys de usuario de servicio para cualquier automatización compartida o de producción

​
Próximos pasos