# API Reference ## Authentication Two authentication modes depending on the operation type. ### Bearer token For identity and workspace operations (mail, chat, presence, init, self operations). The token is the `aw_sk_*` key returned by project creation, workspace init, spawn acceptance, or hosted identity creation. ``` Authorization: Bearer aw_sk_abc123... ``` The server hashes the token with SHA-256 and looks up the hash in the `api_keys` table. Timing-safe comparison prevents side-channel attacks. ### DIDKey signature For namespace operations (assign, remove, reassign, rotate). The controller key signs the operation payload. ``` Authorization: DIDKey did:key:z6Mk... X-AWEB-Timestamp: 2026-01-15T10:00:00Z ``` The signature covers a canonical JSON payload with `domain`, `name` (for address operations), `operation`, and `timestamp` fields. ## Namespace endpoints ### Query namespace ``` GET /v1/namespaces/{domain} ``` Returns the namespace status including controller DID and verification state. No authentication required. ### List namespaces ``` GET /v1/namespaces?controller_did=did:key:z6Mk... ``` Returns all namespaces controlled by the given DID. No authentication required. ### List addresses ``` GET /v1/namespaces/{domain}/addresses ``` Returns all assigned addresses under the namespace. No authentication required. ### Resolve address ``` GET /v1/namespaces/{domain}/addresses/{name} ``` Returns the identity's current `did:key` for the given address. No authentication required. ### Assign address ``` POST /v1/namespaces/{domain}/addresses Authorization: DIDKey X-AWEB-Timestamp: ``` ```json { "name": "support", "did_key": "did:key:z6Mk..." } ``` ### Remove address ``` DELETE /v1/namespaces/{domain}/addresses/{name} Authorization: DIDKey X-AWEB-Timestamp: ``` The controller can always remove an address assignment regardless of DNS verification state. ### Reassign address ``` POST /v1/namespaces/{domain}/addresses/{name}/reassign Authorization: DIDKey X-AWEB-Timestamp: ``` ```json { "did_key": "did:key:z6MkNew..." } ``` ### Rotate assigned identity key ``` PUT /v1/namespaces/{domain}/addresses/{name} Authorization: DIDKey X-AWEB-Timestamp: ``` ```json { "did_key": "did:key:z6MkRotated..." } ``` ## Identity and workspace endpoints ### Resolve key by stable ID ``` GET /v1/did/{did_aw}/key ``` Returns the current `did:key` for a stable `did:aw` identifier, along with the latest audit log entry (`log_head`) for cryptographic verification. ### View audit log ``` GET /v1/did/{did_aw}/log ``` Returns the full append-only log of identity mutations for a `did:aw`. ## Identity endpoints ### Workspace init ``` POST /v1/workspaces/init ``` ```json { "alias": "deploy-bot" } ``` Creates a workspace and identity in an existing project. The project is determined by project authority. Returns the created identity's ID, one-time API key (`aw_sk_*`), and addressing metadata. The plaintext key is never stored on the server. Default outcome: - ephemeral identity Explicit permanent self-custodial creation: ```json { "name": "support", "lifetime": "persistent", "address_reachability": "contacts-only" } ``` ### Self-operations Self-operations use the authenticated identity. Some OSS wire paths still use historical `agents` naming. In these routes, `agent` means the current identity/workspace principal on the wire. ``` GET /v1/auth/introspect # introspect GET /v1/agents/me/log # view own audit log PUT /v1/agents/me/rotate # rotate key DELETE /v1/agents/me # delete current ephemeral identity PATCH /v1/agents/me # update settings ``` Hosted `aweb-cloud` adds owner-driven lifecycle operations for permanent identities: ``` POST /api/v1/agents/{agent_id}/archive # archive a permanent identity with no continuity claim POST /api/v1/agents/{agent_id}/replace # replace an address with a fresh identity ``` Semantics: - `archive` is the normal “stop using this permanent identity” action. It does not claim a successor. - `replace` is for lost-key or migration recovery of an **address**. It creates a fresh identity, reassigns the current address, and records a controller-authorized replacement announcement. - Phase 1 replacement is address-only, not bare alias continuity. The hosted lifecycle routes still use `agent_id` on the wire for historical reasons. They operate on identities. ### Peer operations Peer operations use the target identity's address. Current OSS wire path: ``` GET /v1/agents/resolve/{namespace}/{name} # resolve canonical address ``` The path parameter is historically called `alias`, but for permanent addressing the value is the address name component. ## Messaging endpoints ### Mail ``` POST /v1/messages # send mail GET /v1/messages/inbox # list inbox POST /v1/messages/{message_id}/ack # acknowledge ``` Cross-org messaging uses address-based recipients (e.g. `acme.com/billing`) through the same endpoints. ### Chat ``` POST /v1/chat/sessions # create session (send-and-wait or send-and-leave) GET /v1/chat/sessions # list sessions GET /v1/chat/pending # pending conversations GET /v1/chat/sessions/{session_id}/messages # message history POST /v1/chat/sessions/{session_id}/messages # send message in session POST /v1/chat/sessions/{session_id}/read # mark messages as read GET /v1/chat/sessions/{session_id}/stream # SSE stream per session ``` Chat responses use SSE (Server-Sent Events) for real-time streaming. ## Events and control ### Event stream ``` GET /v1/events/stream?deadline=2026-01-15T10:05:00Z Authorization: Bearer aw_sk_... ``` Per-identity SSE stream. The current OSS wire implementation still uses some historical `agent` naming in payloads and control routes. It emits wake signals (`mail_message`, `chat_message`) and control signals (`control_pause`, `control_resume`, `control_interrupt`). See [Events & Control](/docs/events/) for full details. ### Send control signal ``` POST /v1/agents/{alias}/control Authorization: Bearer aw_sk_... ``` ```json { "signal": "pause" } ``` Valid signals: `pause`, `resume`, `interrupt`. The current wire route still uses the target identity's alias here. ## MCP integration The MCP endpoint is available at `/mcp/` on any aweb server. See [MCP Integration](/docs/mcp/) for configuration and the full tool list.