Agent registration과 authentication boundary
POST /v1/agents/temporary-register는 클라이언트 IP당 UTC 일일 최대 1회, 미할당 temporary Agent와 격리된 Temporary Memory Space를 생성합니다. 이전 /v1/agents/register 경로는 410을 반환합니다. 정식 Agent 생성은 인증된 control plane 엔드포인트를 사용합니다. Agent identity 및 installation metadata는 credential이 아니며 memory authorization 범위를 넓히지 않습니다.
- Temporary registration: POST /v1/agents/temporary-register (익명 허용, 제시된 유효하지 않은 credential은 거부됨).
- Temporary-agent flow: GET /v1/agents/status; GET /v1/agents/bind/status; POST /v1/agents/bind/confirm-current-user; POST /v1/agents/bind/deny-current-user.
- Formal-agent flow: POST /v1/agents/rotate.
Registration request schema
POST /v1/agents/temporary-register는 AgentSelfRegistrationRequest를 허용합니다. 필수 필드는 entry_type, client_name, installation_fingerprint(1..512자) 및 requested_scopes(read:temporary_memory 및 write:temporary_memory의 비어 있지 않은 하위 집합)입니다. 기타 scope는 거부됩니다. 선택적 project 및 installation metadata는 권한을 부여할 수 없습니다.
POST /v1/agents/temporary-register
Content-Type: application/json
{
"entry_type": "mcp",
"client_name": "codex",
"installation_fingerprint": "<stable-installation-fingerprint>",
"requested_scopes": ["read:temporary_memory"],
"client_version": "<client-version>",
"runtime": "windows"
}Registration response schema
성공적인 registration은 required agent_id(string), claim_code(string), bind_url(string), status(string), connection_method(string) 및 trust_level(integer)을 가진 AgentSelfRegistrationResponse를 반환합니다. temporary_token은 optional string 또는 null입니다. Temporary token은 client credential store에만 보관하고 agent identity value로 사용하지 않습니다.
{
"agent_id": "<agent-id>",
"temporary_token": "<temporary-token-or-null>",
"claim_code": "<claim-code>",
"bind_url": "https://xmemo.dev/agents/bind?code=<claim-code>",
"status": "pending",
"connection_method": "streamable_http",
"trust_level": 0
}Status, bind와 rotation schema
OpenAPI는 GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user 및 POST /v1/agents/rotate에 대해 untyped JSON object response와 request body 없음을 선언합니다. POST /v1/agents/bind/confirm-current-user도 OpenAPI에서는 body-untyped이며, 현재 route implementation은 JSON object 또는 query parameter에서 confirmation_token을 읽습니다. Temporary-agent status와 bind response는 committed spec에 property가 선언되지 않은 runtime object입니다. Rotation은 route에 의해 agent에 연결된 formal token으로 제한됩니다.
GET /v1/agents/status
X-API-Key: <temporary-agent-token>
POST /v1/agents/bind/confirm-current-user?confirmation_token=<confirmation-token>
X-API-Key: <temporary-agent-token>
POST /v1/agents/rotate
X-API-Key: <formal-agent-token>Memory call에서 agent attribution
source field는 어떤 agent가 memory를 생성했는지 기록하고 provenance로 저장되지만 authorization에는 영향을 주지 않습니다. Streamable HTTP MCP call에서는 identity header가 client와 안정적인 local install을 설명합니다. REST API는 authenticated key와 optional source/provenance field를 사용하므로 credential은 이 값들과 분리해 보관합니다.
POST /v1/memories
X-API-Key: <your-assigned-api-key>
Content-Type: application/json
{
"content": "Fixed streamable-http token identity fallback.",
"path": "projects/memory-os/fixes",
"source": "codex"
}Error, pagination과 rate limit
Temporary registration은 유효하지 않은 scope 요청에 대해 422, 제시된 유효하지 않은 credential에 대해 401, 폐기된 registration 경로에 대해 410, 1 IP당 UTC 일일 쿼터가 소진되었을 때 429를 반환합니다. 짧은 기간의 요청 제한도 적용됩니다. Status 및 bind 작업에는 자체 credential 검사가 필요합니다.
{
"detail": [
{
"loc": ["body", "installation_fingerprint"],
"msg": "<validation-message>",
"type": "<validation-error-type>"
}
]
}