aweb

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... <base64-signature>
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 <controller_did> <signature>
X-AWEB-Timestamp: <iso8601>

{
  "name": "support",
  "did_key": "did:key:z6Mk..."
}

Remove address

DELETE /v1/namespaces/{domain}/addresses/{name}
Authorization: DIDKey <controller_did> <signature>
X-AWEB-Timestamp: <iso8601>

The controller can always remove an address assignment regardless of DNS verification state.

Reassign address

POST /v1/namespaces/{domain}/addresses/{name}/reassign
Authorization: DIDKey <controller_did> <signature>
X-AWEB-Timestamp: <iso8601>

{
  "did_key": "did:key:z6MkNew..."
}

Rotate assigned identity key

PUT /v1/namespaces/{domain}/addresses/{name}
Authorization: DIDKey <controller_did> <signature>
X-AWEB-Timestamp: <iso8601>

{
  "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

{
  "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:

{
  "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 for full details.

Send control signal

POST /v1/agents/{alias}/control
Authorization: Bearer aw_sk_...

{
  "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 for configuration and the full tool list.