Dos superficies autenticadas
El endpoint MCP alojado y la API REST se autentican de forma distinta. Elige la que corresponda al cliente que estás conectando y nunca coloques una credencial en la configuración pública ni en una URL generada.
- MCP — OAuth cuando el cliente lo admite; de lo contrario Authorization: Bearer ${XMEMO_KEY}.
- Plano de datos REST — X-API-Key: <your-assigned-api-key> (el servidor también acepta Authorization: Bearer <token>). POST /v1/agents/temporary-register permite el registro anónimo según sus condiciones de incorporación y la cuota diaria por IP.
- Los headers de identidad solo sirven para atribución y nunca conceden acceso.
URL base
Establece BASE_URL en el origen del despliegue. El producto alojado usa https://xmemo.dev; el documento OpenAPI versionado también declara http://localhost:8000 para desarrollo local y https://api.memory-os.example.com como servidor de ejemplo. Las llamadas al plano de datos REST usan rutas /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"Header de autenticación REST
La mayoría de las solicitudes REST llevan el header de API key. Las solicitudes sin una credencial válida se rechazan antes de leer o escribir memoria; POST /v1/agents/temporary-register es la excepción documentada de registro temporal. Las credenciales presentadas no válidas se rechazan.
X-API-Key: <your-assigned-api-key>Autenticación MCP
Los clientes OAuth solo necesitan la URL del servidor alojado. Los clientes dinámicos no verificados deben solicitar explícitamente los ámbitos de memoria y conocimiento; los clientes verificados conservan el valor predeterminado existente cuando se omite el ámbito. La concesión proporciona solo los ámbitos aprobados. Los clientes directos y headless leen el token del entorno en su lugar.
{
"servers": {
"XMemo": {
"type": "http",
"url": "https://xmemo.dev/mcp"
}
}
}Scopes
El servidor evalúa los ámbitos de la credencial y el espacio de memoria solicitado por separado. Usa memory:read para recall, search, context, list y lecturas de proyecto; usa memory:write para escrituras y mutaciones. Las operaciones de knowledge requieren estrictamente knowledge:read y rechazan tokens memory:read con 403. Los tokens directos avanzados pueden usar capacidades más restringidas como memory:update, memory:delete, memory:restore, memory:redact o memory:hard_delete. Los alias REST heredados read:memories y write:memories siguen siendo valores de compatibilidad; el ámbito nunca amplía la autorización de propietario, equipo o espacio de token.
- Lectura: memory:read.
- Escritura: memory:write; las operaciones de mutación pueden requerir una capacidad más restringida cuando el perfil del token lo admite.
- Knowledge: knowledge:read; estrictamente requerido para búsqueda y listado de knowledge (tokens memory:read devuelven 403).
- Acceso a proyecto/equipo: el propietario del token o el equipo vinculado y el rol activo también deben autorizar el scope/team_id solicitado.
- Los headers de atribución y los campos source identifican al llamador; no son scopes y no conceden acceso.
Esquema de error
Las rutas OpenAPI declaran HTTPValidationError para la validación de solicitudes (422) y dejan sin tipo la mayoría de los demás esquemas de respuesta. El error REST predeterminado sigue siendo un objeto JSON con un valor detail. Los fallos de autorización reconocidos también pueden solicitarse como application/problem+json al estilo RFC 9457; usa el campo code para el procesamiento automático en lugar de comparar texto libre.
{
"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."
}Límites de velocidad
OpenAPI no publica cuotas de rate limit. El runtime usa una ventana fija de 60 segundos cuando está habilitado (por defecto fuera de development/local/test): la categoría del plano de datos permite 600 solicitudes por minuto, las escrituras de memoria usan una política de endpoint de 180 por minuto y las lecturas de memory search/recall/context usan una política de endpoint de 300 por minuto. Los operadores pueden sobrescribir estos valores con variables de entorno MEMORY_OS_RATE_LIMIT_*; no fijes una cuota en el cliente.
- Respuesta 429: { detail: Rate limit exceeded, category, policy, limit, window_seconds, retry_after_seconds }.
- Headers 429: Retry-After, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset y X-RateLimit-Policy.
- Las respuestas correctas también exponen los headers de límite, remaining, reset y policy de X-RateLimit-* cuando el limiter está habilitado.