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

# Autenticação MCP da Didit: iniciar sessão com OAuth

> Como o MCP da Didit se autentica: OAuth 2.1 com PKCE, registo dinâmico de clientes, metadados de recurso, âmbitos, funções e ligação a cada cliente.

O MCP da Didit autentica-se com **Iniciar sessão com a Didit** (OAuth 2.1). Atua como um **utilizador** da Didit, com as permissões da função que tem na consola. **Não existe modo de chave de API.**

***

## Iniciar sessão com a Didit

O servidor alojado (`https://mcp.didit.me/mcp`) é um **servidor de recursos** OAuth 2.1. A **Didit Business Console** (`business.didit.me`) é o **servidor de autorização** que aloja o ecrã de consentimento e emite os tokens. O seu cliente MCP executa o fluxo padrão automaticamente:

**1. Descoberta**

O cliente envia um pedido POST para `/mcp` sem token e recebe `401` com um cabeçalho `WWW-Authenticate: Bearer` cujo `resource_metadata` aponta para os metadados do recurso protegido (RFC 9728):

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

Este documento indica o recurso (`https://mcp.didit.me/mcp`), o servidor de autorização (`https://business.didit.me`) e os âmbitos suportados. O mesmo documento também é disponibilizado na raiz do domínio, `https://mcp.didit.me/.well-known/oauth-protected-resource`, para os clientes que o procuram primeiro nesse endereço.

**2. Registo (registo dinâmico de clientes)**

O cliente lê os metadados do servidor de autorização em `https://business.didit.me/.well-known/oauth-authorization-server` e, se ainda não tiver um identificador de cliente, regista-se no `registration_endpoint` (RFC 7591). Não tem de pré-configurar nada da sua parte: os clientes locais com um callback de loopback ou nativo (Claude Code, Cursor, MCP Inspector) e os clientes alojados na cloud com um callback revisto (Claude) registam-se desta forma. Um URL de retorno remoto que a Didit não tenha revisto é recusado com `invalid_redirect_uri`; esse cliente tem de ser registado primeiro por um operador.

**3. Autorização (PKCE)**

O cliente abre `https://business.didit.me/authorize` com um desafio PKCE S256. Você inicia sessão (ou regista-se) e vê exatamente que permissões são pedidas. Os clientes são públicos: o endpoint de token não aceita nenhum segredo de cliente (`token_endpoint_auth_methods_supported` é `none`), pelo que é o PKCE que associa o código ao cliente.

**4. Consentimento**

Você aprova. A consola emite uma sessão para essa aplicação, associada aos âmbitos que aprovou, e devolve um código de autorização, que o cliente troca no `token_endpoint` por um token de acesso e um token de atualização.

**5. Chamar ferramentas**

O cliente envia o token de acesso em todos os pedidos. O MCP valida-o com introspeção de token RFC 7662 no serviço de autenticação da Didit (os tokens são opacos, não JWT), lê as permissões da sua organização na resposta de introspeção e atua em **seu** nome durante esse pedido.

### Âmbitos

Os metadados do recurso anunciam três âmbitos. O ecrã de consentimento mostra, em linguagem simples, os que um cliente pede:

| Âmbito | Concede |
| - | - |
| `didit:management` | Gerir o seu espaço de trabalho: `organization`, `members`, `subscription`, `users`, `applications`, `workflows`, `customization`, `questionnaires`, `lists`, `webhooks`, `integrations`, `api-keys`, `audit-logs`, `roles`, `saml` e `analytics`. |
| `didit:verification` | Executar e rever verificações: `sessions`, `businesses`, `cases`, `networks`, `transactions`, `blocklist` e `analytics`. |
| `didit:staff` | Reservado para contas de colaboradores da Didit. Não desbloqueia nada numa conta normal, e a versão de código aberto não define ferramentas exclusivas para colaboradores. |

Ambos os âmbitos incluem `analytics`. Gerir `lists` requer `didit:management`; aceder a `blocklist` requer `didit:verification`.

A [referência das ferramentas](https://docs.didit.me/pt/integration/mcp/tools.md) indica o âmbito a que cada ferramenta pertence. Os âmbitos que aprova ficam associados ao token e são aplicados do lado do servidor, pelo que uma aplicação ligada apenas com `didit:verification` é recusada na área de gestão, mesmo que a sua própria função permitisse essa ação. O servidor de autorização também conhece os âmbitos OpenID (`openid profile email`); uma ligação que peça apenas esses pode saber quem você é e mais nada.

As permissões efetivas de uma aplicação são a **interseção** dos âmbitos aprovados e da sua função na consola, nunca o mais amplo dos dois.

Para criar uma sessão de verificação com `didit_session_create`, precisa do âmbito `didit:verification` **e** de uma função com `create:sessions` ou `write:sessions`. A função **Programador** inclui `create:sessions`. Aprovar apenas `didit:management` não permite criar sessões, mesmo que a sua função tenha a permissão necessária.

### Funções e permissões

O token alojado representa **você**, pelo que o agente pode trabalhar em **todas as organizações a que pertence** numa única ligação. As ferramentas entre aplicações (`didit_session_search`, `didit_analytics`, `didit_context_get` e as restantes ferramentas `*_search`) agregam os resultados de todas elas automaticamente.

A sua **função é sempre imposta** pelo backend da Didit, por organização. Cada ferramenta corresponde a uma cadeia de caracteres de permissão do backend (por exemplo, `write:sessions` para `didit_session_update_status` e `delete:sessions` para `didit_session_delete`); a [referência das ferramentas](https://docs.didit.me/pt/integration/mcp/tools.md) indica a permissão de cada uma. O servidor também verifica essa permissão antes de enviar o pedido, com base nas permissões que a resposta de introspeção indica para a sua organização:

* No modo `enforce`, uma ferramenta que a sua função não pode executar é excluída de `tools/list`, e uma chamada à mesma devolve um erro `missing_scope` que indica a permissão (`"Your role in this organization does not include the permission 'delete:sessions' that didit_session_delete requires."`).
* No modo `shadow` (o predefinido do servidor), todas as ferramentas são listadas e a chamada é enviada ao backend, que responde com `403` quando a função não tem a permissão; o veredicto é apenas registado no registo de auditoria do servidor.

Em qualquer dos casos, o MCP nunca concede mais do que a sua função na consola já permite. Um `READER` pode listar e ler; um `OWNER` ou `ADMIN` pode escrever e eliminar.

### Duração do token

Uma aplicação aprovada recebe a sua própria sessão, separada da sessão do navegador a partir da qual a aprovou. Os tokens de acesso têm vida curta; o cliente renova-os silenciosamente com o token de atualização (`grant_types_supported` inclui `refresh_token`), e a renovação mantém os âmbitos da aplicação e continua associada a essa aplicação. Se uma renovação falhar (por exemplo, depois de desligar a aplicação), o cliente volta a executar **Iniciar sessão com a Didit** na chamada seguinte.

Sair da consola não termina a sessão nas aplicações ligadas, e desligar uma aplicação nunca termina a sua sessão em lado nenhum.

### Desligar uma aplicação

**1. Na consola**

**Definições → Autenticação → Aplicações ligadas** lista cada aplicação que aprovou, com o nome registado e as permissões que lhe foram concedidas. **Desligar** termina de imediato o acesso dessa aplicação: tanto o seu token de acesso como o seu token de atualização deixam de funcionar, e nada mais é afetado.

**2. A partir da aplicação (RFC 7009)**

Um cliente pode revogar o seu próprio acesso enviando o token para o `revocation_endpoint` do servidor de autorização, anunciado nos metadados em `https://business.didit.me/.well-known/oauth-authorization-server`. Tal como o RFC 7009 exige, uma chamada bem-sucedida responde com `200`, quer o token ainda estivesse válido quer não, pelo que a resposta nunca indica se um token era válido. Um `503` significa que a revogação não pôde ser aplicada: trate o token como ainda válido e tente novamente.

```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]
>
> **Porque não há chave de API?** Cada ferramenta MCP chama os endpoints da consola com âmbito de utilizador (`/organization/{org}/application/{app}/…`), que autorizam um token Bearer com privilégios por função e **rejeitam `x-api-key`**. Uma chave de API de aplicação destina-se a chamar a [REST API](https://docs.didit.me/openapi-25.json) diretamente a partir do seu próprio backend (por exemplo, criar sessões), e não a este MCP. `didit_org_list_api_keys` mostra os metadados das chaves com os valores ocultados; a ferramenta que revela uma chave em bruto fica oculta no conector alojado.

***

## Ligar a partir de cada cliente

Todos os clientes seguem o mesmo fluxo; só muda a forma como lhes indica o URL.

> [tab] Claude
>
> Use a ligação direta que a Business Console mostra na sua página de integração. Abre o claude.ai com a caixa de diálogo **Add custom connector** já preenchida:
>
> ```text theme={null}
> https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
> ```
>
> Confirme e depois conclua **Iniciar sessão com a Didit**. O Claude Desktop usa o mesmo URL em **Definições → Conectores → Add custom connector**. Detalhes em [Ligar o Claude](https://docs.didit.me/pt/integration/mcp/claude.md).

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add --transport http didit https://mcp.didit.me/mcp
> ```
>
> Em seguida, execute `/mcp` dentro do Claude Code para iniciar sessão no navegador.

> [tab] Cursor
>
> `~/.cursor/mcp.json`:
>
> ```json theme={null}
> { "mcpServers": { "didit": { "url": "https://mcp.didit.me/mcp" } } }
> ```
>
> O Cursor regista-se a si próprio e abre o navegador na primeira utilização.

> [tab] Cliente genérico
>
> Configure qualquer cliente Streamable HTTP com suporte a OAuth 2.1 para `https://mcp.didit.me/mcp`. Deve:
>
> 1. Fazer `POST /mcp`, receber `401` e ler `resource_metadata` a partir de `WWW-Authenticate`.
> 2. Obter `https://mcp.didit.me/.well-known/oauth-protected-resource/mcp` e, depois, os metadados do servidor de autorização em `https://business.didit.me/.well-known/oauth-authorization-server`.
> 3. Registar-se no `registration_endpoint` se não tiver um ID de cliente.
> 4. Executar o fluxo de código de autorização com PKCE (S256) no `authorization_endpoint` e trocar o código no `token_endpoint`.
> 5. Enviar `Authorization: Bearer <access_token>` em cada `POST /mcp`.
>
> Os clientes sem suporte a OAuth podem funcionar através de `npx -y mcp-remote@latest https://mcp.didit.me/mcp`, que executa os passos 1 a 5 por eles.

***

## Falhas de autenticação

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

Um `401` de `/mcp` significa que o token está em falta, expirou ou foi revogado: o cliente deve renovar o token ou repetir **Iniciar sessão com a Didit**.

Um `403` ou um erro `missing_scope` numa ferramenta *específica* significa normalmente que a sua **função** não tem essa permissão (por exemplo, um `READER` a tentar uma escrita) ou que a ligação foi aprovada **sem o âmbito** que essa ferramenta exige, e não que toda a ligação esteja avariada. Voltar a ligar e aprovar ambos os âmbitos resolve o segundo caso; o primeiro exige uma alteração de função.

Se todas as ferramentas falharem, verifique **Definições → Autenticação → Aplicações ligadas** na consola: uma aplicação que foi desligada aí tem de ser aprovada novamente.

***

> [card] [Referência de ferramentas](https://docs.didit.me/pt/integration/mcp/tools.md)
>
> O que faz cada ferramenta, o seu âmbito e a permissão da sua função.

> [card] [Avançado](https://docs.didit.me/pt/integration/mcp/advanced.md)
>
> Funções, comportamento entre aplicações e alojamento próprio.


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