# 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.

```bash
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

```bash
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

```bash
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

| Operation | Endpoint | Auth |
|-----------|----------|------|
| Resolve address | `GET /v1/namespaces/{domain}/addresses/{name}` | None |
| Assign address | `POST /v1/namespaces/{domain}/addresses` | DIDKey (controller) |
| Remove address | `DELETE /v1/namespaces/{domain}/addresses/{name}` | DIDKey (controller) |
| Reassign address | `POST /v1/namespaces/{domain}/addresses/{name}/reassign` | DIDKey (controller) |
| Rotate identity key | `PUT /v1/namespaces/{domain}/addresses/{name}` | DIDKey (controller) |
| Query namespace | `GET /v1/namespaces/{domain}` | None |
| List namespaces | `GET /v1/namespaces?controller_did=...` | None |
| List addresses | `GET /v1/namespaces/{domain}/addresses` | None |

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