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

# Autenticació MCP de Didit: inici de sessió amb OAuth

> Com s'autentica el MCP de Didit: OAuth 2.1 amb PKCE, registre dinàmic de clients, metadades de recurs, àmbits, rols i com connectar-se des de cada client.

El servidor MCP de Didit s'autentica amb **Iniciar sessió amb Didit** (OAuth 2.1). Actua com un **usuari** de Didit amb els permisos del rol que tens a la consola, i **no hi ha cap mode amb clau d'API**.

***

## Iniciar sessió amb Didit

El servidor allotjat (`https://mcp.didit.me/mcp`) és un **servidor de recursos** OAuth 2.1. La **Didit Business Console** (`business.didit.me`) és el **servidor d'autorització** que aloja la pantalla de consentiment i emet els tokens. El teu client MCP segueix el flux estàndard automàticament:

**1. Descobriment**

El client envia una petició a `/mcp` sense token i rep un `401` amb una capçalera `WWW-Authenticate: Bearer` el `resource_metadata` de la qual apunta a les metadades del recurs protegit (RFC 9728):

```text theme={null}
https://mcp.didit.me/.well-known/oauth-protected-resource/mcp
```

Aquest document indica el recurs (`https://mcp.didit.me/mcp`), el servidor d'autorització (`https://business.didit.me`) i els àmbits admesos. El mateix document també es publica a l'arrel de l'origen, `https://mcp.didit.me/.well-known/oauth-protected-resource`, per als clients que el consulten primer en aquest punt.

**2. Registre (registre dinàmic de clients)**

El client llegeix les metadades del servidor d'autorització a `https://business.didit.me/.well-known/oauth-authorization-server` i, si encara no té un ID de client, es registra a l'`registration_endpoint` (RFC 7591). No cal que facis cap aprovisionament previ: els clients locals amb un callback de loopback o natiu (Claude Code, Cursor, MCP Inspector) i els clients allotjats al núvol amb un callback revisat (Claude) es registren d'aquesta manera. Una URL de callback remota que Didit no ha revisat es rebutja amb `invalid_redirect_uri`; aquest client necessita que un operador el registri primer.

**3. Autoritza (PKCE)**

El client obre `https://business.didit.me/authorize` amb un desafiament PKCE S256. Tu inicies sessió (o et registres) i veus exactament quins permisos es demanen. Els clients són públics: l'endpoint del token no accepta cap secret de client (`token_endpoint_auth_methods_supported` és `none`), de manera que el PKCE és el que lliga el codi al client.

**4. Consentiment**

Tu aproves. La consola crea una sessió per a aquesta aplicació, lligada als àmbits que has aprovat, i retorna un codi d'autorització, que el client intercanvia a l'`token_endpoint` per obtenir un token d'accés i un token de renovació.

**5. Crida les eines**

El client envia el token d'accés amb cada petició. El MCP el valida mitjançant la introspecció de tokens RFC 7662 contra el servei d'autenticació de Didit (els tokens són opacs, no JWT), llegeix els permisos de la teva organització de la resposta d'introspecció i actua com **tu** durant aquella petició.

### Àmbits

Les metadades del recurs anuncien tres àmbits. La pantalla de consentiment mostra en llenguatge senzill els que un client demana:

| Àmbit | Concedeix |
| - | - |
| `didit:management` | Gestiona el teu espai de treball: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` i `analytics`. |
| `didit:verification` | Executa i revisa verificacions: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` i `analytics`. |
| `didit:staff` | Reservat per als comptes del personal de Didit. No desbloqueja res per a un compte habitual, i la versió de codi obert no defineix cap eina exclusiva del personal. |

Ambdós àmbits inclouen `analytics`. Gestionar `lists` requereix `didit:management`; accedir a `blocklist` requereix `didit:verification`.

La [referència d'eines](https://docs.didit.me/ca/integration/mcp/tools.md) indica l'àmbit al qual pertany cada eina. Els àmbits que aproves es transporten al token i s'apliquen al servidor, de manera que una aplicació connectada només amb `didit:verification` es rebutja a la superfície de gestió, fins i tot si el teu rol propi ho permetria. El servidor d'autorització també coneix els àmbits d'OpenID (`openid profile email`); una connexió que només en demani aquests pot saber qui ets i res més.

Els permisos efectius d'una aplicació són la **intersecció** dels àmbits aprovats i del teu rol a la consola, mai el més ampli dels dos.

Per crear una sessió de verificació amb `didit_session_create` necessites l'àmbit `didit:verification` **i** un rol amb `create:sessions` o `write:sessions`. El rol **Desenvolupador** inclou `create:sessions`. Aprovar només `didit:management` no permet crear sessions, encara que el teu rol tingui el permís necessari.

### Rols i permisos

El token emès pel servidor allotjat **et** representa, de manera que l'agent pot treballar a **totes les organitzacions de les quals ets membre** en una única connexió: les eines entre aplicacions (`didit_session_search`, `didit_analytics`, `didit_context_get` i la resta d'eines `*_search`) hi agreguen dades automàticament.

El backend de Didit aplica sempre el teu **rol**, per organització. Cada eina correspon a una cadena de permís del backend (per exemple `write:sessions` per a `didit_session_update_status`, `delete:sessions` per a `didit_session_delete`); la [referència d'eines](https://docs.didit.me/ca/integration/mcp/tools.md) n'indica el permís per eina. El servidor també comprova aquest permís abans d'enviar la petició, fent servir els permisos que la resposta d'introspecció porta per a la teva organització:

* En mode `enforce`, una eina que el teu rol no pot executar s'omet de `tools/list`, i si es crida igualment es retorna un error `missing_scope` que indica el permís (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* En mode `shadow` (el valor per defecte del servidor) totes les eines es mostren i la crida passa al backend, que respon amb `403` si el rol no té el permís; el veredicte només es registra al registre d'auditoria del servidor.

En qualsevol dels dos casos, el MCP mai no concedeix més del que el teu rol de la consola ja permet. Un `READER` pot llistar i llegir; un `OWNER` o un `ADMIN` pot escriure i eliminar.

### Durada del token

Una aplicació aprovada obté la seva pròpia sessió, separada de la sessió del navegador des de la qual l'has aprovat. Els tokens d'accés són de vida curta; el client els renova en silenci amb el token de renovació (`grant_types_supported` inclou `refresh_token`), i una renovació manté els àmbits de l'aplicació i continua lligada a aquesta aplicació. Si una renovació falla (per exemple, després que desconnectis l'aplicació), el client torna a executar **Iniciar sessió amb Didit** a la següent crida.

Tancar la sessió de la consola no tanca la sessió de les aplicacions connectades, i desconnectar una aplicació mai no et tanca la sessió enlloc.

### Desconnectar una aplicació

**1. Des de la consola**

**Settings → Authentication → Connected apps** mostra totes les aplicacions que has aprovat, amb el seu nom registrat i els permisos que se li han concedit. **Desconnectar** acaba l'accés d'aquella aplicació immediatament: tant el seu token d'accés com el seu token de renovació deixen de funcionar, i no afecta res més.

**2. Des de l'aplicació (RFC 7009)**

Un client pot retirar el seu propi accés enviant el token al `revocation_endpoint` del servidor d'autorització, que s'anuncia a les metadades de `https://business.didit.me/.well-known/oauth-authorization-server`. Tal com exigeix la RFC 7009, una crida satisfactòria respon `200` tant si el token encara era vàlid com si no, de manera que la resposta mai no et diu si un token era vàlid. Un `503` vol dir que la revocació no s'ha pogut aplicar: considera que el token encara és vàlid i reintenta.

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

> [!NOTE]
>
> **Per què no hi ha clau d'API?** Totes les eines MCP criden els endpoints de la consola amb abast d'usuari (`/organization/{org}/application/{app}/…`), que autoritzen un token Bearer amb privilegis per rol i **rebutgen `x-api-key`**. Una clau d'API d'aplicació serveix per cridar directament l'[API REST](https://docs.didit.me/openapi-25.json) des del teu propi backend (per exemple, per crear sessions), però no per a aquest MCP. `didit_org_list_api_keys` mostra les metadades de la clau amb els valors ocultats; l'eina que revela una clau en brut està amagada al connector allotjat.

***

## Connectar des de cada client

Tots els clients segueixen el mateix flux; només canvia la manera de indicar-los la URL.

> [tab] Claude
>
> Fes servir l'enllaç directe que la Business Console mostra a la seva pàgina d'integració. Obre claude.ai amb el diàleg **Add custom connector** ja omplert:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Confirma i després completa **Iniciar sessió amb Didit**. Claude Desktop fa servir la mateixa URL a **Settings → Connectors → Add custom connector**. Més detalls a [Connecta Claude](https://docs.didit.me/ca/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Després executa `/mcp` dins de Claude Code per iniciar la sessió al navegador.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> Cursor es registra automàticament i obre el navegador en el primer ús.

> [tab] Client genèric
>
> Apunta qualsevol client Streamable HTTP amb suport d'OAuth 2.1 a `https://mcp.didit.me/mcp`. Hauria de:
>
> 1. Fer `POST /mcp`, rebre un `401` i llegir `resource_metadata` de `WWW-Authenticate`.
> 2. Obtenir `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` i, després, les metadades del servidor d'autorització a `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Registrar-se al `registration_endpoint` si no té un identificador de client.
> 4. Executar el flux de codi d'autorització amb PKCE (S256) al `authorization_endpoint` i intercanviar el codi al `token_endpoint`.
> 5. Enviar `Authorization: Bearer <access_token>` a cada `POST /mcp`.
>
> Els clients sense suport d'OAuth poden funcionar darrere de `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, que fa els passos 1–5 per ells.

***

## Errors d'autenticació

```text theme={null}
HTTP 401
WWW-Authenticate: Bearer error="invalid_token", error_description="Missing Authorization header", resource_metadata="https://mcp.didit.me/.well-known/oauth-protected-resource/mcp"
```

Un `401` des de `/mcp` vol dir que falta el token, ha caducat o s'ha revocat: el client hauria de renovar-lo o tornar a executar **Iniciar sessió amb Didit**.

Un `403` o un error `missing_scope` en una eina *concreta* normalment vol dir que el teu **rol** no té aquell permís (per exemple, un `READER` que intenta una escriptura) o que la connexió s'ha aprovat **sense l'abast** que necessita aquella eina. No vol dir que tota la connexió estigui trencada. Tornar a connectar i aprovar tots dos abasts soluciona el segon cas; el primer requereix canviar el rol.

Si fallen totes les eines, revisa **Settings → Authentication → Connected apps** a la consola: una aplicació que s'ha desconnectat des d'allà s'ha de tornar a aprovar.

***

> [card] [Referència d'eines](https://docs.didit.me/ca/integration/mcp/tools.md)
>
> Què fa cada eina, el seu abast i el permís del seu rol.

> [card] [Avançat](https://docs.didit.me/ca/integration/mcp/advanced.md)
>
> Rols, comportament entre aplicacions i autoallotjament.


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