リファレンスREST APIAPI認証

REST API

API認証

clientとAPI surfaceに応じて、OAuthまたはscope付き環境secretの受け渡しを選択します。

2つの認証済みsurface

hosted MCP endpointとREST APIは異なる方法で認証します。接続するclientに合うほうを選び、public configurationや生成されたURLにcredentialを決して置かないでください。

  • MCP — clientが対応していればOAuth、対応していなければAuthorization: Bearer ${XMEMO_KEY}を使います。
  • REST data plane — X-API-Key: <your-assigned-api-key>（Authorization: Bearer <token>もserverが受け付けます）。POST /v1/agents/temporary-register は、その onboarding 条件および毎日の IP クォータのもとで匿名登録を許可します。
  • Identity headerはattributionだけを示し、accessを付与しません。

Base URL

BASE_URLをdeployment originに設定します。hosted productはhttps://xmemo.devを使い、committed OpenAPI documentにはlocal development用のhttp://localhost:8000とexample serverのhttps://api.memory-os.example.comも宣言されています。REST data-plane callは/v1 pathを使います。

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

REST authentication header

ほとんどのREST requestにはAPI key headerを付けます。有効なcredentialがないrequestは、memoryをreadまたはwriteする前に拒否されます。POST /v1/agents/temporary-register は文書化された temporary registration 例外です。提示された無効な credentials は拒否されます。

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

MCP authentication

OAuth clientに必要なのはhosted server URLだけです。未検証の動的クライアントは memory および knowledge scope を明示的に要求する必要があります。検証済みクライアントは、scope が省略された場合でも既存のデフォルトを保持します。grant は承認された scope のみを提供します。direct および headless client は代わりに環境から token を読み取ります。

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

Scopes

サーバーはcredentialのscopeと要求されたmemory spaceを個別に評価します。recall、search、context、list、project読み取りにはmemory:readを使い、書き込みと変更にはmemory:writeを使います。Knowledge操作には厳密にknowledge:readが必要であり、memory:readトークンは403で拒否されます。高度な直接tokenは、memory:update、memory:delete、memory:restore、memory:redact、memory:hard_deleteなどのより狭い権限を使用できます。レガシーRESTエイリアスread:memoriesとwrite:memoriesは互換性のための値として維持され、scopeがowner、team、またはtoken-spaceの認可を広げることはありません。

  • 読み取り: memory:read。
  • 書き込み: memory:write; token profileがサポートしている場合、mutation操作にはより狭い機能が必要になる場合があります。
  • Knowledge: knowledge:read; knowledgeの検索と一覧表示に厳密に必要です（memory:readトークンは403を返します）。
  • Project/teamアクセス: tokenのownerまたはバインドされたteamとlive roleも、要求されたscope/team_idを認可する必要があります。
  • Attributionヘッダーとsourceフィールドは呼び出し元を識別するだけで、scopeではなくアクセスを許可しません。

Error schema

OpenAPI pathはrequest validation（422）にHTTPValidationErrorを宣言し、それ以外の多くのresponse schemaはuntypedのままです。既定のREST errorはdetail valueを持つJSON objectです。認識されたauthorization failureはRFC 9457-style application/problem+jsonとして要求できる場合もあります。machine handlingではproseの一致ではなくcode fieldを使ってください。

{
  "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."
}

Rate limits

OpenAPIはrate-limit quotaを公開していません。runtimeが有効な場合は60秒のfixed windowを使います（development/local/test以外では既定で有効）。data-plane categoryは毎分600 request、memory writeは毎分180回のendpoint policy、memory search/recall/context readは毎分300回のendpoint policyです。OperatorはMEMORY_OS_RATE_LIMIT_* environment variableで値をoverrideできるため、clientにquotaをhard-codeしないでください。

  • 429 response: { detail: Rate limit exceeded, category, policy, limit, window_seconds, retry_after_seconds }。
  • 429 headers: Retry-After、X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset、X-RateLimit-Policy。
  • limiterが有効な場合、successful responseにもX-RateLimit-*のlimit、remaining、reset、policy headerが公開されます。

出典: Client capability matrix