참조REST APIAPI 인증

REST API

API 인증

연결하는 client와 API surface에 따라 OAuth 또는 scoped environment-secret handoff를 선택합니다.

두 가지 authenticated 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 예외입니다. 제시된 유효하지 않은 credential은 거부됩니다.

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

MCP authentication

OAuth client는 hosted server URL만 필요합니다. 검증되지 않은 동적 클라이언트는 memory 및 knowledge scope를 명시적으로 요청해야 합니다. 검증된 클라이언트는 scope가 생략된 경우 기존 기본값을 유지합니다. grant는 승인된 scope만 제공합니다. direct 및 headless client는 대신 environment에서 token을 읽습니다.

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

Scopes

서버는 자격 증명의 scope와 요청된 memory space를 독립적으로 평가합니다. recall, search, context, list 및 프로젝트 읽기에는 memory:read를 사용하고, 쓰기 및 수정에는 memory:write를 사용합니다. Knowledge 작업에는 엄격히 knowledge:read가 필요하며 memory:read 토큰은 403으로 거부됩니다. 고급 직접 토큰은 memory:update, memory:delete, memory:restore, memory:redact 또는 memory:hard_delete와 같이 더 좁은 권한을 사용할 수 있습니다. 레거시 REST 별칭 read:memories 및 write:memories는 호환성 값으로 유지되며, scope는 owner, 팀 또는 token-space 권한을 확장하지 않습니다.

  • 읽기: memory:read.
  • 쓰기: memory:write; 토큰 프로필이 지원하는 경우 mutation 작업에 더 좁은 권한이 필요할 수 있습니다.
  • Knowledge: knowledge:read; knowledge 검색 및 목록 조회에 엄격히 필요합니다(memory:read 토큰은 403 반환).
  • 프로젝트/팀 접근: 토큰의 owner 또는 연결된 팀 및 활성 역할도 요청된 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 matching 대신 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를 publish하지 않습니다. runtime은 활성화되면 60-second fixed window를 사용하며(개발/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