> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devinenterprise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticación

> Comprende qué son los principals, los tokens y cómo autenticarte con la API de Devin

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.

<div id="principals-tokens">
  ## Principales y tokens
</div>

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

Todas las credenciales de API usan el formato de prefijo `cog_`. Incluye tu token en el encabezado `Authorization` de cada solicitud:

```bash theme={null}
curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer cog_your_token_here"
```

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.

***

<div id="service-users-recommended-for-automation">
  ## Usuarios de servicio (recomendados para la automatización)
</div>

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.

<div id="how-it-works">
  ### Cómo funciona
</div>

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

```bash theme={null}
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"}'
```

<div id="service-user-scopes">
  ### Ámbitos de usuarios de servicio
</div>

| Á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 |

<Tip>
  Encuentra el ID de tu organización en la página **Settings > Service Users**.
</Tip>

<div id="session-attribution-with-create_as_user_id">
  ### Atribución de sesiones con `create_as_user_id`
</div>

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.

<div id="key-properties">
  ### Propiedades clave
</div>

* 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](/es/api-reference/getting-started/teams-quickstart) o la [guía de inicio rápido de Enterprise](/es/api-reference/getting-started/enterprise-quickstart).

***

<div id="personal-access-tokens-closed-beta">
  ## Tokens de acceso personal (beta cerrada)
</div>

<Note>
  Los tokens de acceso personal están actualmente en **beta cerrada** y se habilitan mediante feature flags. [Contacta con soporte](mailto:support@cognition.ai) para obtener acceso. Los PAT no están disponibles para cuentas con SSO/Enterprise.
</Note>

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.

Para obtener más información, consulta [Tokens de acceso personal](/es/api-reference/personal-access-tokens).

***

<div id="legacy-authentication-deprecated">
  ## Autenticación heredada (desaprobada)
</div>

<Warning>
  Las API keys heredadas están desaprobadas. Usa la [API v3](/es/api-reference/v3/overview) con autenticación de usuario de servicio. Consulta la [guía de migración](/es/api-reference/getting-started/migration-guide).
</Warning>

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.

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

**Dónde generarla:** [Settings > API Keys](https://app.devin.ai/settings/api-keys)

***

<div id="security-best-practices">
  ## Prácticas recomendadas de seguridad
</div>

<Warning>
  Nunca compartas API keys en áreas públicamente accesibles, como repositorios de GitHub, código del lado del cliente o registros.
</Warning>

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

<div id="troubleshooting">
  ## Solución de problemas
</div>

<div id="401-unauthorized">
  ### 401 No autorizado
</div>

**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](/es/work-with-devin/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).

<div id="403-forbidden">
  ### 403 Prohibido
</div>

**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

<div id="404-not-found">
  ### 404 No encontrado
</div>

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

<div id="next-steps">
  ## Próximos pasos
</div>

* [Guía de inicio rápido de Teams](/es/api-reference/getting-started/teams-quickstart) — comienza en cuestión de minutos
* [Guía de inicio rápido de Enterprise](/es/api-reference/getting-started/enterprise-quickstart) — configuración de RBAC y multi-organización
* [Flujos comunes](/es/api-reference/common-flows) — ejemplos de flujos de trabajo de principio a fin
* [Guía de migración](/es/api-reference/getting-started/migration-guide) — migra desde las versiones v1/v2