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

# Guia d'integració d'autenticació: arquitectura i sortida en producció

> Com encaixa una integració d'autenticació de Didit en producció: pantalles pròpies o allotjades, tokens, sessions i checklist de sortida.

Aquesta guia explica com encaixa una integració d'Autenticació de Didit en producció, des de la primera redirecció fins a la llista de verificació per a la posada en producció.
Comença per la [guia d'inici ràpid](https://docs.didit.me/ca/authentication/quickstart.md) si encara no has autenticat cap persona, i utilitza les guies d'inici ràpid de la plataforma per al codi de cada SDK.

## Arquitectura

```mermaid theme={null}
sequenceDiagram
    participant App as Your app (browser or mobile)
    participant Hosted as Your Didit sign-in origin
    participant API as Your backend
    participant Webhook as Your webhook endpoint

    App->>Hosted: Open /sign-in (redirect_uri, state, PKCE challenge)
    Note over Hosted: Sign-in method, MFA,<br/>bot protection, verification
    Hosted-->>App: Redirect to redirect_uri with code and state
    App->>Hosted: POST /token/ (code, PKCE verifier)
    Hosted-->>App: Access token (5 min), ID token, refresh token
    App->>API: Request with Authorization: Bearer access token
    Note over API: Verify the signature<br/>with the cached JWKS
    API->>Hosted: GET /session/ before a sensitive action
    Hosted-->>API: Live session, or 401
    Hosted->>Webhook: auth.signup, auth.login, auth.new_device ...
```

Hi intervenen quatre elements:

| Element | Gestiona |
| - | - |
| La teva aplicació | Iniciar la sessió, mantenir el verificador PKCE i `state`, guardar els tokens i enviar el token d'accés al teu backend. Els SDK ho fan tot. |
| El teu origen d'inici de sessió | `https://<slug>.auth.didit.me` (o el teu [domini personalitzat](https://docs.didit.me/ca/authentication/branding-and-custom-domain.md#domini-personalitzat)): les pàgines allotjades, l'endpoint de tokens, la sessió, la descoberta i les claus de signatura. |
| El teu backend | Verificar el token d'accés en cada sol·licitud protegida, comprovar la sessió abans de les accions sensibles i decidir què pot fer la persona. |
| La consola de Didit i els webhooks | La configuració, les persones i les seves sessions, els esdeveniments d'inici de sessió i els webhooks `auth.*` a què es subscriu el teu servidor. |

Cap clau d'API de Didit ni cap secret no han d'estar mai a la teva aplicació: la clau publicable és pública, i l'intercanvi del codi està protegit amb PKCE en lloc d'un secret de client.

## Pàgines allotjades o pantalles pròpies

Tria on les persones introdueixen el seu correu electrònic, contrasenya o codi.
La configuració és `sign_in_ui` (`hosted` per defecte, o `own`), i pots canviar-la més tard.

| | Pàgines allotjades (recomanades) | Les teves pantalles |
| - | - | - |
| Què construeixes | Un botó d'inici de sessió i una pàgina de callback. | Totes les pantalles i tots els passos intermedis. |
| Mètodes | Tots, inclosos els enllaços màgics, l'SSO d'empresa i les passkeys. | Contrasenya, codi per correu electrònic, codi per telèfon, MFA i reptes de protecció mitjançant els mètodes sense interfície dels SDK. Els enllaços màgics només funcionen a les pàgines allotjades. |
| Passos següents | Gestionats per a tu: MFA, inscripció a MFA, reptes de protecció i verificació en el registre. | Les teves pantalles gestionen `mfa_required`, `mfa_enrollment_required`, `protection_required` i `verification_required`. Consulta [mètodes d'inici de sessió](https://docs.didit.me/ca/authentication/sign-in-methods.md). |
| Marca | El teu logotip, colors i textos de [personalització de la marca](https://docs.didit.me/ca/authentication/branding-and-custom-domain.md). | Totalment teva. |
| Configuració | URL de redirecció. | URL de redirecció, més el teu origen web a **Allowed origins**. |

Les passkeys pertanyen a l'origen d'inici de sessió de la teva aplicació.
Els mètodes de passkeys dels SDK només funcionen a les pàgines servides des d'aquest origen, així que, a les teves pantalles pròpies en un altre domini, envia les persones a la pàgina allotjada per a les passkeys.

## Tria el teu SDK

| La teva app | Paquet | On es guarden els tokens |
| - | - | - |
| Aplicació web d'una sola pàgina | [`@didit-protocol/auth`](https://docs.didit.me/ca/authentication/quickstarts/javascript) o [`@didit-protocol/auth-react`](https://docs.didit.me/ca/authentication/quickstarts/react) | Emmagatzematge web o memòria al navegador. Mantén una Content Security Policy estricta. |
| Aplicació web renderitzada al servidor | [`@didit-protocol/auth-nextjs`](https://docs.didit.me/ca/authentication/quickstarts/nextjs) | Cookies HttpOnly establertes pel teu servidor. La pàgina mai no veu els tokens. |
| iOS | [`DiditAuth`](https://docs.didit.me/ca/authentication/quickstarts/ios) | El Keychain. |
| Android | [`me.didit:didit-auth`](https://docs.didit.me/ca/authentication/quickstarts/android) | Emmagatzematge protegit pel Android Keystore. |
| React Native o Flutter | [`@didit-protocol/auth-react-native`](https://docs.didit.me/ca/authentication/quickstarts/react-native) o [`didit_auth`](https://docs.didit.me/ca/authentication/quickstarts/flutter) | L'emmagatzematge protegit de la plataforma, a través dels mòduls natius. |
| Qualsevol backend | [SDK de servidor](https://docs.didit.me/ca/integration/server-sdks/overview.md), `verifyToken` des de `@didit-protocol/auth/server`, o qualsevol biblioteca JWT | No cal emmagatzemar res: verifica el token que rep. |

Si no fas servir cap SDK, implementa tu mateix el flux de codi d'autorització amb PKCE: la [guia d'inici ràpid de JavaScript](https://docs.didit.me/ca/authentication/quickstarts/javascript.md#sense-el-sdk) mostra tot el contracte.

## Protegeix el teu backend

Un control de la sessió al frontend només controla el que mostres.
El teu backend pren cada decisió a partir d'un token verificat.

1. **Verifica el token d'accés en cada sol·licitud.** Comprova la signatura ES256 amb el JWKS del teu emissor, després `iss`, `aud`, `exp` i `typ: at+jwt`, i rebutja qualsevol token amb `act` diferent de `null`, tret que la ruta accepti [agents d'IA](https://docs.didit.me/ca/authentication/agent-access.md). Consulta [com verificar un token al teu servidor](https://docs.didit.me/ca/authentication/tokens-and-jwks.md#verifica-un-token-al-teu-servidor).
2. **Comprova la sessió activa abans d'una acció sensible.** Un token d'accés segueix sent vàlid fins que caduca, com a màxim 5 minuts. `GET /session/` falla immediatament quan la sessió s'ha revocat, ha estat inactiva o ha caducat, quan la persona ha estat bloquejada o quan la sessió ja no compleix la teva política de MFA. Consulta [com comprovar la sessió](https://docs.didit.me/ca/authentication/tokens-and-jwks.md#comprova-la-sessió).
3. **Demana un pas de verificació addicional quan l'acció sigui arriscada.** Abans d'un pagament, d'un compte bancari nou o d'un canvi de correu electrònic o de telèfon, pregunta a Didit si la persona ha de tornar a verificar-se, i actua només amb un pas addicional `approved` que el teu backend hagi llegit per si mateix. Consulta [pas addicional abans d'accions sensibles](https://docs.didit.me/ca/authentication/verified-identity.md#verificació-addicional-abans-de-les-accions-sensibles).
4. **Pren `vendor_data` del token verificat**, mai d'un camp que hagi enviat el navegador, i fes-lo servir per a les verificacions i les transaccions de la persona.

## Sessions

| Esdeveniment | Què passa |
| - | - |
| Inici de sessió | S'inicia una sessió. La seva durada és el valor de `session_lifetime` (30 dies per defecte) i finalitza abans si transcorre `idle_timeout` sense activitat (1 dia per defecte). |
| Cada pocs minuts | El SDK renova el token d'accés, que dura com a màxim 5 minuts. El token de refresc es reemplaça: cadascun només funciona una vegada. |
| Es torna a enviar un token de refresc ja utilitzat | Didit ho considera un robatori i finalitza la sessió. Fes una sola renovació alhora per sessió. |
| Inici de sessió en un altre dispositiu | Amb `multiple_sessions: false`, les altres sessions de la persona finalitzen. |
| Restabliment de la contrasenya | Totes les sessions finalitzen quan `revoke_on_password_change` està activat (per defecte). |
| Tancament de sessió | `DELETE /session/` finalitza la sessió, i la teva aplicació redirigeix la persona a la teva `post_logout_redirect_uri`. |
| El teu equip actua | La consola pot revocar una sessió, tancar la sessió d'una persona a tot arreu o bloquejar-la. Consulta la [guia de la consola](https://docs.didit.me/ca/authentication/console.md#inicis-de-sessió-i-sessions). |

Canvia les durades a **Authentication > Security and sessions**, o per API a la [configuració de l'aplicació](https://docs.didit.me/ca/authentication/overview.md#configuració-de-l’aplicació).

![La vista Active sessions de la Didit Business Console, que enumera les sessions amb inici de sessió i mostra el dispositiu, la ubicació, l'inici, l'última activitat, la finalització i un botó Revoke](https://mintcdn.com/didit-0f962782/RpqZjIB1GnUPdMTN/images/authentication/console-active-sessions.png?fit=max\&auto=format\&n=RpqZjIB1GnUPdMTN\&q=85\&s=098f6be31804b0af7c680e569f341bfb)

Authentication > Sign-ins > Active sessions, amb Revoke a cada sessió.

## Aplicacions natives

Didit retorna les persones a una aplicació nativa només mitjançant una redirecció HTTPS: no accepta esquemes d'URL personalitzats.

* **iOS:** fes que la redirecció sigui un domini associat, amb `webcredentials` al teu `apple-app-site-association`.
* **Android:** fes que la redirecció sigui un App Link, amb el teu `assetlinks.json`.
* Registra cada URL de redirecció a **Authentication > Security and sessions**, igual que un callback web.

Per a les claus d'accés de la teva aplicació, registra amb `PUT native-apps/` les aplicacions que comparteixen les claus d'accés de la teva aplicació a l'[API de gestió d'autenticació](https://docs.didit.me/ca/authentication/set-up-by-api.md).
Didit les inclourà després al `apple-app-site-association` i al `assetlinks.json` que serveix al teu origen d'inici de sessió.
`MANAGEMENT_BASE` és l'adreça de l'API de gestió de la teva aplicació, i una clau d'API amb l'àmbit `authentication` en **escriptura** pot fer la crida.
La crida substitueix les dues llistes, així que envia-les totes dues:

```bash theme={null}
curl --fail-with-body --request PUT "${MANAGEMENT_BASE}native-apps/" \
  -H "x-api-key: $DIDIT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "ios_app_ids": ["ABCDE12345.com.example.app"],
    "android_apps": [
      {
        "package_name": "com.example.app",
        "sha256_cert_fingerprints": ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]
      }
    ]
  }'
```

| Camp | Regla |
| - | - |
| `ios_app_ids` | Fins a 10 entrades amb el teu Team ID i l'identificador de paquet, per exemple `ABCDE12345.com.example.app`. |
| `android_apps` | Fins a 10 aplicacions, cadascuna amb el seu `package_name` i entre 1 i 5 empremtes SHA-256 del certificat de signatura. |

Les guies d'inici ràpid per a [iOS](https://docs.didit.me/ca/authentication/quickstarts/ios.md) i [Android](https://docs.didit.me/ca/authentication/quickstarts/android.md) mostren la part de l'aplicació.

## Connecta la verificació d'identitat i el monitoratge de transaccions

Cada persona té un únic valor de `vendor_data`, tant als seus tokens com a la seva sessió.
Utilitza'l com a `vendor_data` quan [crees una sessió de verificació](https://docs.didit.me/ca/sessions-api/create-session.md) o [envies una transacció](https://docs.didit.me/ca/transaction-monitoring/transactions.md), i la consola mostra els inicis de sessió, les verificacions i les transaccions de la mateixa persona.

* Per verificar les persones en el registre o de nou abans d'un pagament, sense crear un flux de verificació, fes servir [identitat verificada](https://docs.didit.me/ca/authentication/verified-identity.md).
* Els esdeveniments d'inici de sessió arriben automàticament a les [regles d'esdeveniments](https://docs.didit.me/ca/transaction-monitoring/event-rules.md) i a les vistes de frau. No envies els teus propis esdeveniments `auth.login` per als mateixos inicis de sessió.
* Un inici de sessió satisfactori mai aprova una verificació ni una transacció: gestiona la decisió de cada producte per separat.

Consulta [mantén una mateixa persona entre productes](https://docs.didit.me/ca/authentication/overview.md#mantén-una-mateixa-persona-entre-productes).

## Rebre esdeveniments d'inici de sessió

Subscriu una [destinació del webhook](https://docs.didit.me/ca/integration/webhooks.md) als tipus `auth.*` que necessitis, com ara `auth.new_device` o `auth.account_locked`.
Elimina els duplicats amb `auth_event.event_id` i verifica la signatura igual que per a qualsevol webhook de Didit.
Consulta [esdeveniments i webhooks](https://docs.didit.me/ca/authentication/events-and-webhooks.md) per veure tots els tipus i el seu payload.

## Migra els usuaris existents

Si els teus usuaris ja tenen comptes en una altra plataforma d'identitat o a la teva pròpia base de dades, [importa'ls](https://docs.didit.me/ca/authentication/migration.md) abans de canviar el mètode d'inici de sessió.
Importa els hashes de contrasenya quan l'origen els proporcioni, conserva els enllaços a xarxes socials i guarda els teus propis IDs d'usuari com a `external_id`, que es converteix en el seu `vendor_data`.
No canvia res per a ells fins que no canviïs la teva aplicació a Didit.

## Llista de verificació per a la posada en producció

1. La autenticació està activada per a la teva aplicació Live a la pàgina **Products**.
2. Les URL de redirecció `https://` de producció i els orígens permesos estan registrats a l'aplicació Live. Una aplicació Live no accepta adreces `http://`.
3. Cada mètode d'inici de sessió social utilitza el client ID i el secret de la teva pròpia aplicació: les credencials de prova de Didit només funcionen a Sandbox.
4. La configuració de producció conté la clau publicable Live (`pk_live_`) i el teu emissor Live.
5. La política de MFA, la durada de la sessió, el temps d'inactivitat, la longitud de la contrasenya i la política de registre són les que vols. Consulta la [configuració de l'aplicació](https://docs.didit.me/ca/authentication/overview.md#configuració-de-l’aplicació).
6. La [Protecció contra bots](https://docs.didit.me/ca/authentication/bot-protection.md) està activada, amb la comprovació de contrasenyes filtrades.
7. El teu backend verifica cada token d'accés i crida `GET /session/` abans de les accions sensibles.
8. La teva marca, els textos de la pàgina i els enllaços a les condicions d'ús i a la política de privadesa estan configurats. Si tens previst fer servir un [domini personalitzat](https://docs.didit.me/ca/authentication/branding-and-custom-domain.md#domini-personalitzat), activa'l abans que els usuaris comencin a afegir claus d'accés.
9. La destinació del teu webhook està subscrita als tipus `auth.*` que gestiones.
10. Has provat l'alta, l'inici de sessió dels usuaris existents, la cancel·lació, la recuperació de la contrasenya, el MFA, la caducitat de la sessió, el tancament de sessió i una sessió revocada a l'aplicació Live.

## Resolució de problemes

| Símptoma | Causa i solució |
| - | - |
| Totes les rutes d'execució responen `404` | L'autenticació està desactivada per a l'aplicació, o l'adreça barreja un sandbox i un origen de producció. Activa-la des de la pàgina **Products**, i fes servir l'origen que indica la teva clau publicable. |
| La pàgina d'inici de sessió respon `400` i et demana que registris una adreça, o `POST /authorize/` respon `invalid_redirect_uri` | El `redirect_uri` no està registrat exactament: l'esquema, l'host, el port, el camí i els paràmetres de consulta han de coincidir caràcter a caràcter. Consulta [URL de redirecció](https://docs.didit.me/ca/authentication/overview.md#url-de-redirecció). |
| Una crida des del navegador al teu origen d'inici de sessió respon `403` amb `origin_not_allowed` | El teu origen web no és a **Allowed origins**. Afegeix-lo sense camí i sense barra final. |
| `POST /token/` respon `invalid_grant` | El codi ja s'ha fet servir, té més de 60 segons, o s'ha enviat amb un altre verificador PKCE o un altre `redirect_uri`. Si es tracta d'una renovació, el token de renovació ja s'havia fet servir, cosa que finalitza la sessió. Torna a iniciar sessió. |
| Un inici de sessió amb contrasenya respon `invalid_credentials` amb la contrasenya correcta | El correu electrònic no està verificat, o el compte està bloquejat o inhabilitat. Didit dona la mateixa resposta de manera intencionada. Revisa la persona a **Users**. |
| `GET /session/` respon `401` | La sessió s'ha revocat, ha estat inactiva o ha caducat, la persona ha estat bloquejada, el token s'ha substituït per un token de renovació, o la sessió ja no compleix la teva política de MFA. Refresca el token o torna a iniciar sessió amb la persona. |
| Afegir una clau d'accés o un autenticador respon `403 reauthentication_required` | Això requereix una sessió creada en els últims 5 minuts. Primer torna a iniciar sessió amb la persona. |
| Un codi per telèfon respon `503 delivery_unavailable` | No s'ha pogut lliurar el codi. Deixa que la persona ho torni a intentar, o ofereix-li un altre mètode. |
| Una crida respon `429` | Has superat un límit de freqüència. Torna a intentar-ho després del temps indicat a `Retry-After`. Consulta [límits de freqüència](https://docs.didit.me/ca/authentication/bot-protection.md#límits-de-freqüència). |
| Una crida de configuració amb una clau d'API respon `409 product_disabled` | L'autenticació està desactivada per a l'aplicació. Una persona l'activa a la consola. |
| Una crida respon `403 plan_required` | La funcionalitat, com ara els rols personalitzats o els enllaços de configuració d'SSO d'empresa, requereix el pla Scale o Enterprise. Les aplicacions de sandbox la tenen activada en qualsevol pla. |
| Els tokens fallen després d'activar un domini personalitzat | Han canviat l'emissor i la clau publicable. Copia la clau nova a la teva aplicació, i actualitza l'emissor que comprova el teu sistema de backend. |


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