Agent registration and authentication boundary
POST /v1/agents/temporary-register 用于创建未领取的 temporary Agent 以及隔离的 Temporary Memory Space，每个客户端 IP 每个 UTC 日最多调用一次。旧的 /v1/agents/register 路径返回 410。正式 Agent 创建使用经过认证的 control plane endpoints。Agent identity 和 installation metadata 不是 credentials，也不会扩大 memory authorization。
- Temporary registration：POST /v1/agents/temporary-register（允许匿名；提交的无效凭据将被拒绝）。
- 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 返回 AgentSelfRegistrationResponse，其中 required fields 是 agent_id（string）、claim_code（string）、bind_url（string）、status（string）、connection_method（string）和 trust_level（integer）。temporary_token 是可选的 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, and rotation schemas
OpenAPI 声明 GET /v1/agents/status、GET /v1/agents/bind/status、POST /v1/agents/bind/deny-current-user 和 POST /v1/agents/rotate 返回 untyped JSON object，且没有 request body。POST /v1/agents/bind/confirm-current-user 在 OpenAPI 中同样 body-untyped；当前 route implementation 从 JSON object 或 query parameter 读取 confirmation_token。Temporary-agent status 和 bind responses 是 runtime objects，其 properties 未在 committed spec 中声明。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>Agent attribution on memory calls
source field 记录产生 memory 的 agent，并作为 provenance 保存；它不影响 authorization。对于 streamable HTTP MCP calls，identity headers 描述 client 和稳定的本地 install。REST API 使用 authenticated key，以及可选的 source/provenance fields；请将 credentials 与这些 values 分开。
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"
}Errors, pagination, and rate limits
Temporary registration 在 scope 请求无效时返回 422，提交无效凭据时返回 401，访问已废弃的 registration 路径时返回 410，单 IP 每日（UTC）配额用尽时返回 429。短时间窗口的请求限制同样适用。Status 和 bind 操作需要独立的凭据校验。
{
"detail": [
{
"loc": ["body", "installation_fingerprint"],
"msg": "<validation-message>",
"type": "<validation-error-type>"
}
]
}