# API認証

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

- Canonical: https://docs.xmemo.dev/ja/docs/api/authentication
- Locale: ja-JP
- Content-Locale: ja-JP
- Canonical-Content-Digest: 2ccb101521e35878569be22c158ebf3f733f976c32f1b7952809dc29ffb5dba5
- Edition-Digest: 0eefc2f096183dd669b14720cd3c444acffa57806bf0ebf0f26e1316ce9cbb78
- Source-Revision: sha256:0f4e5aaa7eba4f6a045f2818119002c0ddba188a30db4cee7ebfd8a2164d3e96

## 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を使います。

```bash
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 は拒否されます。

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

## MCP authentication

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

```json
{
  "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を使ってください。

```json
{
  "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が公開されます。