Agenten-Registrierung und Authentifizierungsgrenze
POST /v1/agents/temporary-register erstellt höchstens einmal pro Client-IP und UTC-Tag einen nicht beanspruchten temporären Agenten und einen isolierten temporären Speicherbereich. Der alte Pfad /v1/agents/register gibt 410 zurück. Die formelle Agentenerstellung verwendet authentifizierte Endpunkte der Steuerungsebene. Agentenidentitäts- und Installations-Metadaten sind keine Anmeldedaten und erweitern die Speicherautorisierung nicht.
- Temporäre Registrierung: POST /v1/agents/temporary-register (anonym zulässig; ungültige vorgelegte Anmeldedaten werden abgelehnt).
- Ablauf für temporäre Agenten: GET /v1/agents/status; GET /v1/agents/bind/status; POST /v1/agents/bind/confirm-current-user; POST /v1/agents/bind/deny-current-user.
- Ablauf für formelle Agenten: POST /v1/agents/rotate.
Schema der Registrierungsanfrage
POST /v1/agents/temporary-register akzeptiert AgentSelfRegistrationRequest. Erforderliche Felder sind entry_type, client_name, installation_fingerprint (1..512 Zeichen) und requested_scopes (eine nicht leere Teilmenge von read:temporary_memory und write:temporary_memory). Andere Scopes werden abgelehnt. Optionale Projekt- und Installations-Metadaten können keine Berechtigungen erteilen.
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"
}Schema der Registrierungsantwort
Eine erfolgreiche Registrierung liefert AgentSelfRegistrationResponse mit den erforderlichen Feldern agent_id (string), claim_code (string), bind_url (string), status (string), connection_method (string) und trust_level (integer). temporary_token ist ein optionaler string oder null. Speichern Sie ein temporäres Token ausschließlich im Anmeldedatenspeicher des Clients; es ist kein Agentenidentitätswert.
{
"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
}Schemas für Status, Bindung und Rotation
OpenAPI deklariert eine typlose JSON-Objektantwort und keinen Anfrage-Body für GET /v1/agents/status, GET /v1/agents/bind/status, POST /v1/agents/bind/deny-current-user und POST /v1/agents/rotate. POST /v1/agents/bind/confirm-current-user ist in OpenAPI ebenfalls bezüglich des Bodys typlos; die aktuelle Routen-Implementierung liest confirmation_token aus einem JSON-Objekt oder Abfrageparameter aus. Status- und Bindungsantworten temporärer Agenten sind Laufzeitobjekte, deren Eigenschaften nicht in der committeten Spezifikation deklariert sind. Die Rotation wird durch die Route auf ein formelles Token beschränkt, das mit einem Agenten verknüpft ist.
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>Agentenzuordnung bei Speicheraufrufen
Das Feld source zeichnet auf, welcher Agent einen Speicher erzeugt hat, und wird als Herkunftszuordnung gespeichert; es hat keinen Einfluss auf die Autorisierung. Für streamable HTTP MCP-Aufrufe beschreiben Identitäts-Header den Client und die stabile lokale Installation. Die REST-API verwendet den authentifizierten Schlüssel sowie optionale source/Herkunftsfelder; halten Sie Anmeldedaten stets getrennt von diesen Werten.
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"
}Fehler, Paginierung und Rate-Limits
Die temporäre Registrierung gibt 422 bei ungültigen Scope-Anfragen zurück, 401 bei ungültigen vorgelegten Anmeldedaten, 410 beim eingestellten Registrierungspfad und 429, wenn das Kontingent von einer IP pro UTC-Tag erschöpft ist. Es gelten auch Anfragelimits für kurze Zeitfenster. Status- und Bindungsoperationen erfordern eigene Anmeldedatenprüfungen.
{
"detail": [
{
"loc": ["body", "installation_fingerprint"],
"msg": "<validation-message>",
"type": "<validation-error-type>"
}
]
}