> ## 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 l'autenticació de Didit per API

> Activa mètodes d'inici de sessió a Didit des del teu codi amb una concessió aprovada o una clau d'API amb àmbit d'autenticació.

Didit Authentication et permet activar mètodes d'inici de sessió i consultar mitjançant l'API la configuració de la teva aplicació. Fes servir una concessió aprovada pel propietari o una clau d'API amb nom i l'àmbit `authentication`.

> [!WARNING]
>
> Authentication és una funcionalitat nova. Configura un mètode primer en una aplicació de sandbox i després en la teva aplicació de producció.

Cada crida que es mostra a continuació va a l'API de gestió d'Authentication de la teva aplicació. `MANAGEMENT_BASE` és:

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

Les mateixes rutes es descriuen a `openapi-authentication.json` sota l'etiqueta `Setup`, a partir del qual es regeneren els SDK de servidor.

## Quina credencial utilitzar

Funciona qualsevol de les tres credencials, i cadascuna està limitada al que el seu titular ha aprovat.

| Credencial | S'envia com a | Què pot fer |
| - | - | - |
| Clau d'API amb nom i amb l'àmbit `authentication` | `x-api-key: <key>` | Configura la seva pròpia aplicació i la llegeix. Una clau amb `read` només pot llegir la configuració; `write` la pot llegir i canviar. |
| Autorització aprovada pel titular amb `didit:management` | `Authorization: Bearer <access_token>` | Configura les aplicacions de les organitzacions aprovades en el consentiment, dins del rol de la persona. |
| Sessió de la consola | `Authorization: Bearer <console session token>` | Llegeix o canvia la configuració segons la pertinença de la persona a l'organització i el seu rol. Les vistes d'usuari final també requereixen una sessió de la consola i els permisos adequats. |

Aquestes credencials es rebutgen amb `403` en totes les rutes de configuració, sigui quina sigui la petició:

* El **secret principal** de l'aplicació.
* Un token de `POST /programmatic/login`, que s'emet per a l'aplicació i no per a la consola.
* Una clau **sense** l'àmbit `authentication`, inclosa una clau creada amb tots els recursos al nivell màxim: aquestes es mostren com a accés complet, mantenen `scopes` buit i no s'accepten en aquestes rutes.
* Una clau d'**una altra aplicació**, una autorització limitada a `didit:verification`, i una autorització aprovada per a una altra organització.

Una petició sense cap credencial rep `401` com a resposta. Una autorització o una clau mantenen, a més, els seus propis límits: l'autorització, els seus àmbits, les organitzacions i el rol de la persona; la clau, els seus àmbits, la llista d'IP permeses i la data de caducitat.

## Aprobar el acceso

### Amb una clau d'API amb nom

Obre **Developers -> API keys** a la [Business Console](https://business.didit.me) i crea una clau per a l'aplicació que estàs configurant. Dona-li el recurs `authentication` amb permís de **read** o **write**: read cobreix totes les crides que llegeixen la configuració (`GET`); write cobreix totes les crides que la canvien (`POST`, `PUT`, `PATCH`, `DELETE`) i també la llegeixen. Consulta [Claus d'API](https://docs.didit.me/ca/console/api-keys.md) per a la caducitat, les llistes d'IP permeses i la rotació; una clau pertany a una aplicació i només funciona per a aquesta.

### A través d'una connexió MCP

Un agent connectat al servidor MCP de Didit utilitza el permís que el seu propietari ha aprovat a la pantalla de consentiment, amb `didit:management`. Consulta [Autenticació MCP](https://docs.didit.me/ca/integration/mcp/authentication.md#inicia-sessió-amb-didit).

### Per a un propietari sense contrasenya

La concessió de codi de dispositiu ([RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628)) permet que un propietari que inicia sessió amb Google, una clau d'accés o un codi enviat per correu electrònic aprovi el mateix accés des de qualsevol navegador, sense escriure cap contrasenya. Consulta [iniciar sessió sense navegador](https://docs.didit.me/ca/integration/mcp/authentication.md#inicia-sessió-sense-navegador-codi-de-dispositiu).

## Activar el codi per correu electrònic

`PUT methods/{name}/` accepta només `enabled` per a un mètode que no necessita credencials.

```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}'
```

La resposta mostra el mètode tal com està ara:

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

Quan llegeixis la configuració, l'entrada del codi per correu electrònic inclou `credential_source: null`. Els mètodes que sempre estan activats no es poden desactivar: aquesta sol·licitud respon amb `{"enabled": "always_on"}`.

## Activa Google

Un mètode social fa servir les credencials de la teva pròpia aplicació OAuth, o les de l'aplicació de prova de Didit en una aplicació de sandbox.

### Amb la teva pròpia aplicació 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 retorna la resposta al teu proveïdor. El secret és només d'escriptura: cap resposta no el retorna, i `client_id` és l'única part que pots llegir de nou. Activar un mètode sense credencials, quan abans no n'hi havia cap d'emmagatzemada, respon `{"credentials": "required"}`.

### Amb l'aplicació de prova de Didit (`didit_test`)

Una **aplicació de sandbox** pot fer servir les aplicacions socials pròpies de Didit en lloc de les teves, cosa que és suficient per acabar una configuració i comprovar 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` cobreix **Google, Microsoft, Apple i GitHub**, només en aplicacions de sandbox:

| Resposta | Quan |
| - | - |
| `{"credential_source": "sandbox_only"}` | L'aplicació està en producció. Les aplicacions de prova mai no serveixen inicis de sessió en producció. |
| `{"credential_source": "unavailable"}` | El desplegament no té una aplicació de prova per a aquest proveïdor, de manera que el mètode continua desactivat. |
| `200` amb `configured: true` | L'aplicació de prova serveix el mètode, i l'inici de sessió allotjat el mostra. |

`GET` sobre la configuració indica en `didit_test_credentials` els proveïdors que una aplicació de prova pot servir per a aquesta aplicació. El valor és `false` per als quatre en una aplicació en producció.

## Llegir la configuració

`GET` sobre `MANAGEMENT_BASE` és la lectura de comprovació: cada mètode amb `enabled` i `credential_source`, a més de les URL de callback, les regles de sessió i la política de registre.

```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"]
}
```

Els mètodes desactivats també apareixen a la llista, de manera que un sol `GET` indica què està activat i què no. `enabled` a la part superior és `false` quan l'Autenticació està desactivada per a l'aplicació. Qualsevol canvi de configuració fet amb un permís de gestió o amb una clau d'API amb nom retorna `409` amb `{"detail": "product_disabled"}`, i no s'escriu res. Cap crida de configuració no activa l'Autenticació: una persona l'activa per a l'aplicació a la consola, i a partir d'aquell moment les teves crides funcionen.

## La resta de la configuració

| Ruta, sota `MANAGEMENT_BASE` | Mètodes | Què conté |
| - | - | - |
| `settings/` | `GET`, `PATCH` | Accés dels agents, organitzacions, la política de MFA, el rol predeterminat dels membres, els esdeveniments de webhook desactivats |
| `onboarding/` | `GET`, `PATCH` | Quins passos de la configuració estan fets, i si els usuaris inicien sessió a la pàgina allotjada o a les teves pròpies pantalles |
| `branding/` | `GET`, `PATCH` | Els textos i els enllaços legals de les pàgines allotjades (el logotip i els colors provenen de Personalització) |
| `protection/` | `GET`, `PATCH` | Les polítiques de protecció contra bots ([protecció contra bots](https://docs.didit.me/ca/authentication/bot-protection.md)) |
| `verified/` | `GET`, `PATCH` | El nivell de verificació del registre, les regles de verificació reforçada i les afirmacions dels tokens |
| `emails/`, `emails/{key}/` | `GET` | Els correus d'inici de sessió que envia aquesta aplicació, i una vista prèvia renderitzada |
| `domain/` | `GET`, `PUT`, `DELETE` | L'origen allotjat i el domini personalitzat d'inici de sessió |
| `domain/verify/`, `domain/activate/` | `POST` | Comprova el DNS i el certificat del domini i, després, el converteix en l'origen canònic |
| `native-apps/` | `GET`, `PUT` | Les aplicacions d'iOS i Android que comparteixen les passkeys de l'aplicació |

Una concessió o una clau només poden accedir a la configuració i als seus comptadors, mai a dades d'usuaris finals: `users/`, `sessions/`, `sign-ins/`, `overview/`, les organitzacions de clients, els rols, les importacions, les sessions d'agents i els correus de prova continuen necessitant una sessió de la consola.

La configuració `agent_humans_only` s'aplica a tota l'aplicació. Només un propietari o administrador de l'organització en pot canviar el valor. Una clau amb nom rep `403 owner_or_admin_required`. Activar la configuració també requereix una passkey registrada (`passkey_required`).

## Errors

| Resposta | Significat |
| - | - |
| `401` | Sense credencial. |
| `403` | Una credencial que no pot configurar aquesta aplicació, o un dels seus propis límits: `ip_not_allowed`, una clau caducada o una clau de només lectura en una ruta d'escriptura. |
| `409 {"detail": "product_disabled"}` | L'autenticació està desactivada per a l'aplicació, de manera que es rebutja qualsevol canvi de configuració fet amb una concessió o una clau. Una persona l'activa a la consola. |
| `400 {"<field>": "<code>"}` | `sandbox_only`, `unavailable`, `not_supported`, `required`, `always_on`, `method_unavailable`, `unknown_field`. |
| `404` | No s'ha pogut trobar el recurs sol·licitat. |


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