Autenticação da API

Duas superfícies autenticadas

O endpoint MCP hospedado e a API REST usam autenticação diferente. Escolha a opção correspondente ao cliente que você está integrando e nunca coloque uma credencial em uma configuração pública ou em uma URL gerada.

• MCP — OAuth quando o cliente oferecer suporte; caso contrário, Authorization: Bearer ${XMEMO_KEY}.
• Plano de dados REST — X-API-Key: <your-assigned-api-key> (Authorization: Bearer <token> também é aceito pelo servidor). POST /v1/agents/temporary-register permite registro anônimo sob suas condições de integração e cota diária por IP.
• Cabeçalhos de identidade servem apenas para atribuição e nunca concedem acesso.

URL base

Defina BASE_URL como a origem da implantação. O produto hospedado usa https://xmemo.dev; o documento OpenAPI versionado também declara http://localhost:8000 para desenvolvimento local e https://api.memory-os.example.com como servidor de exemplo. As chamadas do plano de dados REST usam caminhos /v1.

BASE_URL="${BASE_URL:-https://xmemo.dev}"
curl -sS "$BASE_URL/v1/recall?query=connection%20check&limit=1" \
  -H "X-API-Key: $XMEMO_KEY"

Cabeçalho de autenticação REST

A maioria das solicitações REST leva o cabeçalho de chave da API. Solicitações sem uma credencial válida são rejeitadas antes que qualquer memória seja lida ou gravada; POST /v1/agents/temporary-register é a exceção documentada de registro temporário. Credenciais apresentadas inválidas são rejeitadas.

X-API-Key: <your-assigned-api-key>

Autenticação MCP

Clientes OAuth precisam apenas da URL do servidor hospedado. Clientes dinâmicos não verificados devem solicitar explicitamente os escopos de memória e conhecimento; clientes verificados mantêm o padrão existente quando o escopo é omitido. A concessão fornece apenas os escopos aprovados. Clientes diretos e headless leem o token do ambiente.

{
  "servers": {
    "XMemo": {
      "type": "http",
      "url": "https://xmemo.dev/mcp"
    }
  }
}

Escopos

O servidor avalia os escopos da credencial e o espaço de memória solicitado separadamente. Use memory:read para recall, search, context, list e leituras de projeto; use memory:write para gravações e mutações. Operações de knowledge exigem estritamente knowledge:read e rejeitam tokens com memory:read com 403. Tokens diretos avançados podem usar capacidades mais restritas, como memory:update, memory:delete, memory:restore, memory:redact ou memory:hard_delete. Os aliases REST legados read:memories e write:memories continuam sendo valores de compatibilidade; o escopo nunca amplia a autorização do proprietário, da equipe ou do espaço do token.

• Leitura: memory:read.
• Gravação: memory:write; operações de mutação podem exigir uma capacidade mais específica quando o perfil do token oferecer suporte.
• Knowledge: knowledge:read; estritamente necessário para busca e listagem de knowledge (tokens memory:read retornam 403).
• Acesso ao projeto/equipe: o proprietário do token ou a equipe vinculada, além da função ativa, também devem autorizar o escopo/team_id solicitado.
• Cabeçalhos de atribuição e campos source identificam o chamador; não são escopos e não concedem acesso.

Formato de erro

Os caminhos OpenAPI declaram HTTPValidationError para validação da solicitação (422) e deixam sem tipo a maioria dos demais esquemas de resposta. O erro REST padrão continua sendo um objeto JSON com um valor detail. Falhas de autorização reconhecidas também podem ser solicitadas como application/problem+json no estilo RFC 9457; use o campo code no tratamento de máquina, em vez de comparar texto.

{
  "detail": "invalid_token"
}

{
  "type": "urn:xmemo:problem:invalid_token",
  "title": "Invalid access token",
  "status": 401,
  "code": "invalid_token",
  "detail": "The presented access token is missing, expired, revoked, or otherwise invalid."
}

Limites de requisição

O OpenAPI não publica cotas de limite de requisições. O runtime usa uma janela fixa de 60 segundos quando habilitado (habilitado por padrão fora de development/local/test): a categoria do plano de dados permite 600 solicitações por minuto, gravações de memória usam uma política de 180 por minuto e leituras de busca/recall/context usam uma política de 300 por minuto. Os operadores podem substituir esses valores com as variáveis de ambiente MEMORY_OS_RATE_LIMIT_*; não fixe uma cota no cliente.

• Resposta 429: { detail: Rate limit exceeded, category, policy, limit, window_seconds, retry_after_seconds }.
• Cabeçalhos 429: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset e X-RateLimit-Policy.
• Respostas bem-sucedidas também expõem os cabeçalhos X-RateLimit-* de limite, restante, redefinição e política quando o limitador está habilitado.