> ## Documentation Index
> Fetch the complete documentation index at: https://docs.morada.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Autenticação

> OAuth 2.1, API keys e escopos do servidor MCP da Morada.ai.

## Métodos suportados

O servidor MCP aceita dois métodos de autenticação:

| Método               | Quando usar                                            | Identificação                              |
| -------------------- | ------------------------------------------------------ | ------------------------------------------ |
| **OAuth 2.1 (PKCE)** | Clientes interativos: Claude, Cursor, ChatGPT, VS Code | Login pelo navegador, tokens com expiração |
| **API Key**          | Automações, scripts, clientes sem suporte a OAuth      | Token estático com prefixo `mak_`          |

Os dois métodos passam pelo mesmo controle de permissões e escopos.

## OAuth 2.1

O servidor implementa **OAuth 2.1 com PKCE** e **Dynamic Client Registration (DCR)**, seguindo a [especificação oficial de auth do MCP](https://modelcontextprotocol.io).

### Endpoints

| Endpoint             | URL                                                                   |
| -------------------- | --------------------------------------------------------------------- |
| Discovery            | `https://app.morada.ai/api/mcp/well-known/oauth-authorization-server` |
| Authorize            | `https://app.morada.ai/api/mcp/oauth/authorize`                       |
| Token                | `https://app.morada.ai/api/mcp/oauth/token`                           |
| Dynamic Registration | `https://app.morada.ai/api/mcp/oauth/register`                        |

### Fluxo

<Steps>
  <Step title="Discovery">
    O cliente MCP busca o documento `.well-known/oauth-authorization-server` e descobre todos os endpoints e escopos suportados.
  </Step>

  <Step title="Dynamic Client Registration">
    Se o cliente ainda não tem um `client_id`, ele se registra automaticamente em `/oauth/register` e recebe um `client_id` público (sem `client_secret` — apenas PKCE).
  </Step>

  <Step title="Authorization">
    O cliente abre o navegador na URL de `authorize` com um `code_challenge`. O usuário faz login na Morada.ai e vê a tela de **consentimento** com os escopos solicitados.
  </Step>

  <Step title="Token exchange">
    Após aprovar, o cliente recebe um `authorization_code`, troca por um `access_token` (e `refresh_token`) em `/oauth/token` usando PKCE.
  </Step>

  <Step title="Uso">
    Toda chamada ao MCP envia `Authorization: Bearer <access_token>`. Quando o token expira, o cliente usa o `refresh_token` automaticamente.
  </Step>
</Steps>

<Info>
  Tokens OAuth carregam o **conjunto de escopos** aprovado pelo usuário. Mesmo que o usuário tenha permissão total na plataforma, o cliente só pode chamar tools cobertas pelos escopos concedidos.
</Info>

## API Key

API keys são úteis para automações ou clientes que não suportam OAuth.

### Criando uma API key

<Steps>
  <Step title="Abra Configurações da Conta">
    Na plataforma, clique no seu avatar → **Configurações da conta**.
  </Step>

  <Step title="Localize MCP API Keys">
    Role até a seção **MCP API Keys**.
  </Step>

  <Step title="Gere uma nova chave">
    Informe um **nome** descritivo (ex.: `automação-relatórios`), escolha o **nível de acesso** e clique em **Gerar**.

    | Nível               | Escopos incluídos                                                                                                |
    | ------------------- | ---------------------------------------------------------------------------------------------------------------- |
    | **Somente leitura** | `conversations:view` `deals:view` `instances:view` `integrations:view` `dashboard:view` `message-templates:view` |
    | **Acesso completo** | Acima + `instances:edit` `integrations:edit` `talk:edit` `message-templates:edit`                                |
  </Step>

  <Step title="Copie a chave imediatamente">
    O token completo (`mak_...`) é exibido **apenas uma vez**. Guarde em local seguro.

    <Warning>
      Após fechar o diálogo, só o prefixo da chave fica visível. Se perder o token completo, será necessário revogar e gerar uma nova.
    </Warning>
  </Step>
</Steps>

### Usando a API key

Envie no header `Authorization`:

```bash theme={null}
curl https://app.morada.ai/api/mcp \
  -H "Authorization: Bearer mak_SUA_API_KEY" \
  -H "Content-Type: application/json"
```

Em clientes MCP, configure o header customizado:

```json theme={null}
{
  "mcpServers": {
    "morada-platform": {
      "url": "https://app.morada.ai/api/mcp",
      "headers": {
        "Authorization": "Bearer mak_SUA_API_KEY"
      }
    }
  }
}
```

### Revogando uma API key

Na mesma tela de **MCP API Keys**, clique no ícone de lixeira ao lado da chave e confirme. A revogação é imediata.

<Tip>
  A coluna **Último uso** ajuda a identificar chaves inativas que podem ser revogadas com segurança.
</Tip>

## Escopos disponíveis

Cada escopo libera um conjunto de ferramentas. O usuário ainda precisa ter a permissão correspondente na plataforma para que a chamada seja autorizada.

| Escopo                   | Ferramentas liberadas                                                  |
| ------------------------ | ---------------------------------------------------------------------- |
| `conversations:view`     | `list_conversations`, `get_conversation`, `list_conversation_messages` |
| `deals:view`             | `list_deals`, `get_deal`                                               |
| `instances:view`         | `list_agents`, `get_agent`                                             |
| `integrations:view`      | `list_integrations`, `get_integration`                                 |
| `dashboard:view`         | `get_analytics`                                                        |
| `talk:edit`              | `send_active_message`                                                  |
| `message-templates:view` | `list_message_templates`                                               |
| `message-templates:edit` | `create_message_template`                                              |

A ferramenta `list_workspaces` não exige escopo específico — todo token autenticado pode descobrir os workspaces do usuário.

## Como a autorização é avaliada

Em toda chamada, o servidor verifica:

<Steps>
  <Step title="Token válido">
    O token (OAuth ou API key) existe, não expirou e está associado a um usuário ativo.
  </Step>

  <Step title="Escopo concedido">
    A ferramenta solicitada está coberta pelos escopos do token.
  </Step>

  <Step title="Permissão na plataforma">
    O usuário tem a permissão correspondente (ex.: `Deals.View`) no workspace alvo, herdada do seu papel.
  </Step>

  <Step title="Pertencimento ao workspace">
    Para tools que recebem `workspaceId`, o usuário precisa ter acesso àquele workspace específico.
  </Step>
</Steps>

<Warning>
  Se qualquer uma das checagens falhar, a chamada retorna erro de autorização — independente da permissão dos demais escopos.
</Warning>

## Próximos passos

<Columns cols={2}>
  <Card title="Instalação" icon="download" href="/mcp/instalacao">
    Conectar Claude, Cursor, ChatGPT e outros clientes.
  </Card>

  <Card title="Ferramentas" icon="wrench" href="/mcp/ferramentas">
    Catálogo completo de tools expostas pelo MCP.
  </Card>
</Columns>