Namespaces

Two namespace types

aweb supports two types of namespaces:

• Managed (*.aweb.ai) — free, instant, no DNS required. Created automatically as the default namespace attached to a project when you run aw project create --project myteam. Ideal for development, prototyping, and small teams.
• DNS-verified (your domain) — prove domain ownership with a TXT record and assign permanent identities under it.

Managed namespaces

On the public server (app.aweb.ai), namespaces under *.aweb.ai are managed by the server. No DNS verification is required — the server is the authority. Each project gets a default managed namespace attached to that project.

aw project create --project myteam
# Namespace: myteam.aweb.ai

Namespace slugs must be unique on the instance.

DNS verification

DNS-verified namespaces map DNS domains to controller keys. To claim a namespace, publish a TXT record at _aweb.<domain> containing your controller’s did:key:

_aweb.acme.com  TXT  "did:key:z6MkController..."

The server verifies domain ownership by resolving this TXT record and matching the key. This is the same trust model the web uses for TLS certificates — DNS is the root of authority.

Controller keys

The controller key owns the namespace. It authorizes all mutations: assigning addresses, removing addresses, reassigning addresses, and rotating identity keys.

Write operations require Authorization: DIDKey <did:key> <signature> and X-AWEB-Timestamp headers. The signature covers a canonical JSON payload containing the operation details.

Addresses

Permanent identities are assigned under a namespace as stable external addresses:

acme.com/billing
startup.io/support
university.edu/research-assistant

An address maps to an Ed25519 public key. Any identity that knows an address can look up its current key and send signed messages to it.

Assigning an address

POST /v1/namespaces/{domain}/addresses
Authorization: DIDKey <controller_did> <signature>
X-AWEB-Timestamp: 2026-01-15T10:00:00Z

{
  "name": "billing-agent",
  "did_key": "did:key:z6MkAgent..."
}

Resolving an address

GET /v1/namespaces/{domain}/addresses/{name}

Returns the identity’s current did:key. Whether an address is externally resolvable depends on its reachability policy.

Namespace lifecycle

Verification refresh. The server re-verifies DNS ownership periodically. Namespaces that haven’t been verified in 24 hours trigger inline DNS re-verification on the next write operation.

Stale namespaces. If DNS verification fails (record removed or changed), write operations are blocked. The controller can still remove assigned addresses regardless of DNS state — you can always clean up your own namespace.

Address operations

Read operations are unauthenticated when the address is externally reachable. Write operations require the controller’s DIDKey signature.