Use stable non-secret agent identity metadata while credentials remain in authenticated request headers.
Agent registration and authentication boundary
The public /v1/agents surface supports temporary agent self-registration, status polling, two-phase bind confirmation, and formal-token rotation. POST /v1/agents/register accepts an optional authenticated principal; the remaining agent endpoints require the API key associated with the agent. Agent identity and installation metadata are not credentials and do not widen memory authorization.
- Self-registration: POST /v1/agents/register (the only listed agent endpoint with an optional auth dependency).
- 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/register accepts AgentSelfRegistrationRequest. Required fields are entry_type (string), client_name (string), and installation_fingerprint (string, 1..512 characters). Optional fields are project_id, metadata, client_version, runtime, device_id_hash, environment_id, workspace_path_hash, project_id_hash, skill_package_id, and mcp_server_id; nullable fields are represented as string or null in OpenAPI.
POST /v1/agents/register
Content-Type: application/json
{
"entry_type": "mcp",
"client_name": "codex",
"installation_fingerprint": "<stable-installation-fingerprint>",
"client_version": "<client-version>",
"runtime": "windows"
}
Registration response schema
A successful registration returns AgentSelfRegistrationResponse with required agent_id (string), claim_code (string), bind_url (string), status (string), connection_method (string), and trust_level (integer). temporary_token is an optional string or null. Store a temporary token only in the client credential store; it is not an 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 declares an untyped JSON object response and no request body for GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user, and POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user is also body-untyped in OpenAPI; the current route implementation reads confirmation_token from a JSON object or query parameter. Temporary-agent status and bind responses are runtime objects whose properties are not declared in the committed spec. Rotation is restricted by the route to a formal token associated with an agent.
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
The source field records which agent produced a memory and is stored as provenance; it does not affect authorization. For streamable HTTP MCP calls, identity headers describe the client and stable local install. The REST API uses the authenticated key plus optional source/provenance fields; keep credentials separate from these 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
Agent endpoints declare HTTPValidationError for registration validation failures (422) where OpenAPI has a request model; untyped endpoints have no stronger response or error schema in the document. Runtime auth errors use the shared {detail: string} contract or the opt-in application/problem+json contract on the Authentication page. Status and bind endpoints do not expose pagination parameters. The runtime places these /v1 paths in the 600-per-minute data-plane category inside a configurable 60-second window; no agent-specific rate limit is published in OpenAPI.
{
"detail": [
{
"loc": ["body", "installation_fingerprint"],
"msg": "<validation-message>",
"type": "<validation-error-type>"
}
]
}