# Mind Key vs JWT — qual usar quando?

O Synapse tem dois tokens de autenticação. Escolher o errado leva a erros 401.
Este guia oferece uma estrutura clara de decisão.

## Tabela de decisão rápida

| Você quer... | Use |
|--------------|-----|
| Armazenar / recuperar memórias | Mind Key |
| Enviar / fazer poll de mensagens de chat | Mind Key |
| Gerenciar tarefas | Mind Key |
| Armazenar scripts | Mind Key |
| Registrar webhooks | Mind Key |
| Controlar computadores | Mind Key (lado do usuário) / Computer Token (lado do agente) |
| Registrar uma conta de usuário | Nenhum (público) |
| Fazer login | Nenhum (público) |
| Criar / listar / excluir minds | JWT |
| Compartilhar um mind com outro usuário | JWT |
| Inscrever-se em notificações web push | JWT |
| Ver log de auditoria | Mind Key |

## A regra simples

> [!TIP]
> **Se toca os dados de um único mind → Mind Key.**
> **Se gerencia a conta ou metadados de mind → JWT.**

## Mind Key — token de acesso a dados

Uma Mind Key concede acesso aos **dados de um mind**. É um token de longa
duração que nunca expira (até o mind ser excluído). Perfeita para:

- Agentes LLM persistindo memórias entre sessões
- Cron jobs em background
- Configuração de servidor MCP
- Integrações de webhook
- Apps mobile lendo memória

### O que a Mind Key pode fazer

- `GET /memory/recall` — ler todas as memórias neste mind
- `POST /memory` — armazenar/atualizar memórias
- `GET /chat/poll` — ler mensagens de chat
- `POST /chat/reply` — enviar mensagens de chat
- `GET /mind/tasks` — listar tarefas
- `POST /mind/task` — criar tarefas
- `POST /script` — armazenar scripts
- `POST /webhooks` — registrar webhooks
- `POST /computers/:id/commands` — enfileirar comandos de computador

### O que a Mind Key NÃO pode fazer

- Criar / listar / excluir minds (precisa de JWT)
- Compartilhar mind com outro usuário (precisa de JWT)
- Ver informações da conta do usuário (precisa de JWT)
- Inscrever-se em web push (precisa de JWT)

## JWT — token de gerenciamento de conta

Um JWT autentica a **conta do usuário**. Ele expira após 7 dias e é usado para
operações em nível de conta que abrangem múltiplos minds ou envolvem outros
usuários.

### O que o JWT pode fazer

- `POST /minds` — criar um novo mind (retorna uma nova Mind Key)
- `GET /minds` — listar todos os minds deste usuário
- `DELETE /minds/:id` — excluir um mind
- `POST /sharing` — compartilhar um mind com outro usuário
- `POST /push/subscribe` — inscrever em notificações web push
- `GET /sharing` — listar compartilhamentos de mind

### O que o JWT NÃO pode fazer

- Ler / escrever memórias (precisa de Mind Key)
- Enviar mensagens de chat (precisa de Mind Key)
- Gerenciar tarefas (precisa de Mind Key)
- Registrar webhooks (precisa de Mind Key)

## Caso especial: Computer Token

Os endpoints `/computers/me/*` (voltados ao agente, para o screen-remote-agent)
usam um terceiro tipo de token: o **Computer Token**. Esse token é retornado por
`POST /computers/register` ao resgatar um código de instalação, e é específico
para um computador registrado.

| Endpoint | Auth |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key ou JWT |
| `POST /computers/:id/commands` | Mind Key ou JWT |

## Padrões comuns

### Padrão 1: agente LLM único

1. Registre uma vez → obtenha JWT
2. Crie um mind → obtenha Mind Key
3. LLM usa a Mind Key para tudo

### Padrão 2: agente multi-projeto

1. Registre uma vez → obtenha JWT
2. Crie múltiplos minds (work, personal, project-x) → obtenha múltiplas Mind Keys
3. LLM carrega Mind Key diferente com base no contexto

### Padrão 3: compartilhamento em equipe

1. Usuário A cria um mind → obtém Mind Key A
2. Usuário A compartilha com Usuário B via JWT (`POST /sharing`)
3. Usuário B agora pode acessar via seu próprio JWT
4. Para acesso LLM, Usuário B precisa criar sua própria Mind Key (ou usar a de A)

### Padrão 4: servidor MCP

Servidores MCP sempre usam Mind Key (definida via variável de ambiente
`SYNAPSE_MIND_KEY`). Uma instância de servidor MCP = um mind. Para acesso
multi-mind, rode múltiplas instâncias MCP ou implemente troca de mind no cliente.

## Tabela de formato de tokens

| Token | Formato | Exemplo |
|-------|---------|---------|
| Mind Key | `mk_` + 36 chars | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 chars | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## Próximos passos

- [Autenticação](/docs/getting-started/authentication) — guia completo de auth
- [API de Usuário e Minds](/docs/api/user) — endpoints protegidos por JWT
- [API de Memória](/docs/api/memory) — endpoints protegidos por Mind Key