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

# Authentication

> How the Didit MCP authenticates: Log in with Didit (OAuth 2.1 + PKCE). The MCP acts as a Didit user — there is no API-key mode. Scopes, multi-org, and role permissions.

The Didit MCP authenticates with **Log in with Didit** (OAuth 2.1). It acts as a Didit **user** with your console role's permissions — **there is no API-key mode**.

***

## Log in with Didit

The hosted server (`https://mcp.didit.me/mcp`) is an OAuth 2.1 **resource server**. The **Didit Business Console** (`business.didit.me`) is the **authorization server** that hosts the consent screen and issues tokens. Your MCP client drives the standard flow automatically:

<Steps>
  <Step title="Discover">
    The client connects, gets a `401` with the protected-resource metadata, and discovers the authorization server.
  </Step>

  <Step title="Authorize (PKCE)">
    The client opens `business.didit.me/authorize` with a PKCE challenge. You sign in (or register) and see exactly which permissions are requested.
  </Step>

  <Step title="Consent">
    You approve. The console returns an authorization code, which the client exchanges for an access token (and a refresh token).
  </Step>

  <Step title="Call tools">
    The client sends the access token with every request. The MCP validates it and acts as **you**.
  </Step>
</Steps>

Clients that support **Dynamic Client Registration** (Claude, Cursor, …) register themselves automatically — there is nothing to pre-provision on your side.

### Scopes

The connector requests two coarse scopes, shown in plain language on the consent screen:

| Scope                | Grants                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `didit:management`   | Manage your workspace — workflows, sessions, lists, webhooks, members, billing, analytics. |
| `didit:verification` | Run verifications — KYC, KYB, AML, biometrics, OCR, and the standalone APIs.               |

### Multi-organization & roles

The hosted token represents **you**, so the agent can work across **every organization you belong to** in a single connection — cross-app tools (`didit_session_search`, `didit_analytics`, `didit_context_get`) aggregate over all of them automatically.

Your **role is always enforced** server-side. A `READER` can list and read but write calls return a permission error; an `OWNER`/`ADMIN` can write. The MCP never grants more than your console role already allows.

### Token lifetime

Access tokens are short-lived; the client silently refreshes them with the refresh token. If a refresh fails (e.g. revoked access), the client re-runs **Log in with Didit** on the next call. To disconnect, remove the connector in your client or revoke access in the console.

<Note>
  **Why no API key?** Every MCP tool calls the user-scoped console endpoints (`/organization/{org}/application/{app}/…`), which authorize a Bearer token with per-role privileges and **reject `x-api-key`**. An application API key is for calling the [REST API](/openapi-25.json) directly from your own backend (e.g. creating sessions) — not for this MCP. Tools like `didit_org_reveal_application_api_key` manage those REST keys; they are not how the MCP itself authenticates.
</Note>

***

## Auth failures

A `403` means re-authenticate — **reconnect / re-run Log in with Didit**:

```text theme={null}
HTTP 403
{ "detail": "You do not have permission to perform this action." }
```

A `403` on a *specific* tool usually means your **role** lacks that permission (e.g. a `READER` attempting a write), not that the whole connection is broken.

***

<CardGroup cols={2}>
  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    What each tool does and which are write/destructive.
  </Card>

  <Card title="Advanced" icon="gear" href="/integration/mcp/advanced">
    Scopes, cross-app behavior, and self-hosting.
  </Card>
</CardGroup>