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

# Configurar la autenticación de Didit por API

> Configura métodos de inicio de sesión, ajustes, marca y protección en Didit desde tu código, con una concesión aprobada o una clave de autenticación.

Didit Authentication te permite habilitar métodos de inicio de sesión y leer la configuración de tu aplicación mediante la API. Usa una concesión aprobada por el propietario o una clave de API con nombre y el ámbito `authentication`.

> [!WARNING]
>
> Authentication es nuevo. Configura primero un método en una aplicación de sandbox y, después, en tu aplicación de producción.

Todas las llamadas siguientes van a la API de gestión de Authentication de tu aplicación. `MANAGEMENT_BASE` es:

```text theme={null}
https://apx.didit.me/auth/v2/organizations/{org_id}/applications/{application_id}/authentication/
```

Las mismas rutas se describen en `openapi-authentication.json`, bajo la etiqueta `Setup`; los SDK de servidor se regeneran a partir de este archivo.

## Qué credencial usar

Cualquiera de las tres credenciales funciona, y cada una se limita a lo que su titular aprobó.

| Credencial | Se envía como | Qué puede hacer |
| - | - | - |
| Clave de API con nombre y con el ámbito `authentication` | `x-api-key: <key>` | Configura su propia aplicación y la lee. Una clave con `read` solo puede leer la configuración; una con `write` puede leerla y modificarla. |
| Concesión aprobada por el titular con `didit:management` | `Authorization: Bearer <access_token>` | Configura las aplicaciones de las organizaciones aprobadas en el consentimiento, dentro del rol de la persona. |
| Sesión de la consola | `Authorization: Bearer <console session token>` | Lee o modifica la configuración según la pertenencia de la persona a la organización y su rol. Las vistas de usuarios finales también requieren una sesión de la consola y los permisos adecuados. |

Estas credenciales se rechazan con `403` en todas las rutas de configuración, sea cual sea la solicitud:

* El **secreto principal** de la aplicación.
* Un token de `POST /programmatic/login`, que se emite para la aplicación y no para la consola.
* Una clave **sin** el ámbito `authentication`, incluida una clave creada con todos los recursos en su nivel más alto: se muestra como acceso completo, mantiene `scopes` vacío y no se acepta en estas rutas.
* Una clave de **otra aplicación**, una concesión limitada a `didit:verification` y una concesión aprobada para otra organización.

Una solicitud sin ninguna credencial responde con `401`. Además, una concesión o una clave mantiene sus propios límites: la concesión, sus ámbitos, sus organizaciones y el rol de la persona; la clave, sus ámbitos, su lista de IP permitidas y su caducidad.

## Aprobar el acceso

### Con una clave de API con nombre

Abre **Developers -> API keys** en la [Business Console](https://business.didit.me) y crea una clave para la aplicación que estás configurando. Asígnale el recurso `authentication` con permiso de **lectura** o de **escritura**: la lectura cubre todas las llamadas que leen la configuración (`GET`); la escritura cubre todas las llamadas que la cambian (`POST`, `PUT`, `PATCH`, `DELETE`) y también permite leerla. Consulta [claves de API](https://docs.didit.me/es/console/api-keys.md) para la caducidad, las listas de IP permitidas y la rotación; una clave pertenece a una sola aplicación y solo funciona para ella.

### A través de una conexión MCP

Un agente conectado al servidor MCP de Didit usa la concesión que su propietario aprobó en la pantalla de consentimiento, con `didit:management`. Consulta [autenticación MCP](https://docs.didit.me/es/integration/mcp/authentication.md#iniciar-sesión-con-didit).

### Para un propietario sin contraseña

La concesión de código de dispositivo ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) permite que un propietario que inicie sesión con Google, una clave de acceso o un código enviado por correo electrónico apruebe el mismo acceso desde cualquier navegador, sin escribir una contraseña. Consulta [iniciar sesión sin navegador](https://docs.didit.me/es/integration/mcp/authentication.md#iniciar-sesión-sin-navegador-código-de-dispositivo).

## Habilitar código por correo electrónico

`PUT methods/{name}/` acepta `enabled`, y nada más para un método que no necesita credenciales.

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/code/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'
```

Responde con el método tal como está ahora:

```json theme={null}
{"name": "code", "enabled": true}
```

Al leer la configuración, la entrada del código por correo electrónico incluye `credential_source: null`. Los métodos que siempre están activos no se pueden desactivar: esa solicitud responde `{"enabled": "always_on"}`.

## Activar Google

Un método social usa las credenciales de tu propia aplicación OAuth, o la app de prueba de Didit en una aplicación sandbox.

### Con tu propia aplicación de Google

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credentials": {"client_id": "1234.apps.googleusercontent.com", "client_secret": "GOCSPX-..."}}'
```

Registra el `callback_uri` que devuelve la respuesta en tu proveedor. El secreto es de solo escritura: ninguna respuesta lo devuelve, y `client_id` es la única parte que puedes volver a leer. Activar un método sin credenciales, cuando no se había guardado ninguna anteriormente, responde `{"credentials": "required"}`.

### Con la app de prueba de Didit (`didit_test`)

Una **aplicación sandbox** puede usar las apps sociales de Didit en lugar de las tuyas, lo que basta para completar una configuración y comprobar que funciona:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}methods/google/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"enabled": true, "credential_source": "didit_test"}'
```

`didit_test` cubre **Google, Microsoft, Apple y GitHub**, solo en aplicaciones sandbox:

| Respuesta | Cuándo |
| - | - |
| `{"credential_source": "sandbox_only"}` | La aplicación está en producción. Las apps de prueba nunca atienden inicios de sesión en producción. |
| `{"credential_source": "unavailable"}` | El despliegue no tiene una app de prueba para ese proveedor, así que el método permanece desactivado. |
| `200` con `configured: true` | La app de prueba atiende el método, y ofrece esta opción en el inicio de sesión alojado. |

`GET` sobre la configuración indica en `didit_test_credentials` los proveedores que una app de prueba puede atender para esta aplicación. El valor es `false` para los cuatro en una aplicación en producción.

## Leer la configuración

`GET` en `MANAGEMENT_BASE` es la lectura de la configuración: cada método con `enabled` y `credential_source`, además de las URL de callback, las reglas de sesión y la política de registro.

```bash theme={null}
curl --fail-with-body "$MANAGEMENT_BASE" -H "x-api-key: $DIDIT_API_KEY"
```

```json theme={null}
{
  "enabled": true,
  "methods": [
    {"name": "code", "enabled": true, "credential_source": null},
    {"name": "google", "enabled": true, "credential_source": "didit_test", "configured": true, "client_id": "didit-test-google"},
    {"name": "password", "enabled": false, "credential_source": null}
  ],
  "didit_test_credentials": {"google": true, "microsoft": true, "apple": true, "github": true},
  "redirect_uris": ["https://app.example.com/auth/callback"]
}
```

Los métodos deshabilitados también aparecen en la lista, así que un solo `GET` indica qué está activado y qué no. `enabled` en la parte superior es `false` cuando la Autenticación está deshabilitada para la aplicación. Cualquier cambio de configuración que se haga con un permiso de gestión o con una clave con nombre devuelve `409` con `{"detail": "product_disabled"}`, y no se guarda nada. Ninguna llamada de configuración activa la Autenticación: la activa una persona para la aplicación en la consola, y tus llamadas funcionan a partir de ese momento.

## El resto de la configuración

| Ruta, bajo `MANAGEMENT_BASE` | Métodos | Qué contiene |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Acceso de agentes, organizaciones, la política de MFA, el rol predeterminado de miembro y los eventos de webhook deshabilitados |
| `onboarding/` | `GET`, `PATCH` | Qué pasos de la configuración están completados y si los usuarios inician sesión en la página alojada o en tus propias pantallas |
| `branding/` | `GET`, `PATCH` | Los textos y los enlaces legales de las páginas alojadas (el logotipo y los colores proceden de Personalización) |
| `protection/` | `GET`, `PATCH` | Las políticas de protección contra bots ([protección contra bots](https://docs.didit.me/es/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | El nivel de verificación del registro, las reglas de verificación adicional y las declaraciones del token |
| `emails/`, `emails/{key}/` | `GET` | Los correos de inicio de sesión que envía esta aplicación y una vista previa renderizada |
| `domain/` | `GET`, `PUT`, `DELETE` | El origen alojado y el dominio personalizado de inicio de sesión |
| `domain/verify/`, `domain/activate/` | `POST` | Comprueba el DNS y el certificado del dominio y, después, lo establece como origen canónico |
| `native-apps/` | `GET`, `PUT` | Las apps de iOS y Android que comparten las claves de acceso de la aplicación |

Una concesión o una clave solo pueden acceder a la configuración y a sus contadores, nunca a datos de usuarios finales: `users/`, `sessions/`, `sign-ins/`, `overview/`, las organizaciones de clientes, los roles, las importaciones, las sesiones de agentes y los correos de prueba siguen necesitando una sesión de la consola.

El ajuste `agent_humans_only` se aplica a toda la aplicación. Solo un propietario o administrador de la organización puede cambiarlo. Una clave con nombre recibe `403 owner_or_admin_required`. Activar el ajuste también requiere una clave de acceso registrada (`passkey_required`).

## Errores

| Respuesta | Significado |
| - | - |
| `401` | Sin credencial. |
| `403` | Una credencial que no puede configurar esta aplicación, o uno de sus propios límites: `ip_not_allowed`, una clave expirada o una clave de solo lectura en una ruta de escritura. |
| `409 {"detail": "product_disabled"}` | La autenticación está desactivada para la aplicación, por lo que se rechaza un cambio de configuración realizado con una concesión o una clave. Una persona la activa en la consola. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | No se pudo encontrar el recurso solicitado. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.