// dns-rooted identity registry

Global identity
for agents

Cryptographic identities under your own domain. Addresses and audit trails survive key rotation and server moves — verifiable by anyone, rooted in DNS.

$ aw id create how trust works →
addressacme.com/support
stable identitydid:aw:2CiZ88h…
current signing keydid:key:z6MkehRg…OK_VERIFIED
resolve.sh
$ curl https://api.awid.ai/v1/namespaces/acme.com/addresses/support

{
  "did_aw": "did:aw:2CiZ88hVF4JuQim8nnSuyeiV2HF2",
  "current_did_key": "did:key:z6MkehRgf7yJ…",
  "delivery": { "origin": "https://app.aweb.ai" }
}
# chain verified · OK_VERIFIED · hash-log head matches cache

// the trust model

Who says you are who you say?

Every time an agent acts for you, the other side asks one question: who is this, and do they really speak for their team? awid answers it with no account at all — the chain traces back to a domain you already own.

Chain of trust: how an awid identity is verifiedA vertical diagram of five layers, each signed by the layer above, verifiable back up to one DNS record only the domain owner can publish.
Trust flows down — each layer signed by the one above. Verification traces back up to the one DNS record only your domain can publish.

You already prove who you are every day

You own a domain. When someone loads acme.com, they already trust that you — and only you — control it. awid turns that fact into identity: you publish one DNS record that says this key speaks for acme.com. No signup form, no company letting you in. The root of trust is something you already hold.

see the actual record
dns
# published once, at the domain you control
_awid.acme.com  TXT  "awid=v1; controller=did:key:z6Mk…"
# add registry=https://…  to self-host; otherwise api.awid.ai

A key you can replace without becoming a stranger

Keys get compromised or expire. If your identity were the key, replacing it would make you a stranger to everyone. So awid splits identity in two — like keeping your passport number while you replace a worn-out signature. Your stable id never changes; your signing key rotates anytime. Every change is appended to a signed log, so a verifier tells an ordinary rotation from a suspicious one.

see how an identity is named
identity
did:aw:2CiZ88h…             # the stable identity — this is "you"
  ├─ did:key:z6MkehRg…    # current signing key; rotates
  └─ acme.com/alice        # a public handle bound to the identity

A team is a group your domain vouches for

One identity is not a team. The domain's controller creates one — backend:acme.com — with a key of its own. That team key signs a certificate for each member: a small card saying this key belongs to this team. No central platform manages it, so no one can forge membership — and a teammate can even live on another domain: partner.com/bob can hold a card for your team.

look inside a certificate
certificate
{
  "team_id":        "backend:acme.com",
  "member_did_key": "did:key:z6Mk…",   # the key this card authorizes
  "member_address": "acme.com/alice",
  "identity_scope": "global",
  "signature":      "…"               # signed by the team key
}

Proving it, one request at a time

A card can be photocopied — so every time an agent acts, it signs the exact request: this action, this path, this body, this audience, this moment. The app re-checks each against what arrived, traces the card back to the key your domain published, and confirms the member wasn't revoked. A single mismatch locks the door.

see the bytes a request signs
request
# one signature covers all of this
{ "v":2, "method":"POST", "path":"/v1/documents",
  "body_sha256":"…", "aud":"https://api.acme.com",
  "team_id":"backend:acme.com", "timestamp":"…Z" }

// append-only key log

Every resolution returns a verdict

Each stable identity keeps a hash-chained, signed log of key changes. Verifiers check the log head on every resolution and compare it against their local cache.

OK_VERIFIED

Signature and hash chain verify. Cache is consistent. The identity is trusted.

OK_DEGRADED

Usable, but full cryptographic verification couldn't complete. Falls back to trust-on-first-use.

HARD_ERROR

Regression, split view, or broken hash chain. Reject the resolution.

// http api

Anonymous reads. Signed writes.

Discovery is public and rate-limited. Mutation requires an Ed25519 signature. The same registry runs at api.awid.ai or on your own infrastructure.

Public reads

GET/v1/did/{did_aw}/keyResolve the current signing key for a stable identity.
GET/v1/namespaces/{domain}/addresses/{name}Resolve an address to identity, key, and delivery origin.
GET/v1/namespaces/{domain}/teams/{name}/members/{alias}Resolve one active team member certificate by alias.
GET/v1/namespaces/{domain}/teams/{name}/revocationsFetch the team's published revocation list.

Authenticated writes

POST/v1/didRegister a stable identity with signed creation evidence.
PUT/v1/did/{did_aw}Rotate keys or update the published server.
POST/v1/namespaces/{domain}/teams/{name}/certificatesIssue a signed team certificate for a member.
POST/v1/namespaces/{domain}/teams/{name}/certificates/revokeRevoke a member certificate and publish the change.
Signed writes use Ed25519 signature auth: Authorization: DIDKey <did:key> <sig> plus X-AWEB-Timestamp. Identity-scoped messaging adds X-AWEB-DID-AW to bind the sender — no team certificate required just to send.

// get started

Create an identity in one command

aw id create generates a keypair, walks you through DNS setup, and registers the identity. The address is established at creation time.

aw id create
$ aw id create --name support --domain acme.com

Generating Ed25519 keypair…
Add this TXT record to _awid.acme.com:
  awid=v1; controller=did:key:z6MkehRgf7yJbgaGfYsdoAsKdBPE3dj2CYhowQdcjqSJgvVd;

Verifying DNS…       ok
Registering namespace  acme.com
Registering address    acme.com/support
Registering identity   did:aw:2CiZ88hVF4JuQim8nnSuyeiV2HF2

Address:  acme.com/support
did:aw:   2CiZ88hVF4JuQim8nnSuyeiV2HF2
Registry: api.awid.ai

// the aweb repository

One MIT-licensed repo, three parts

awid

This identity registry. Resolves addresses, manages namespaces, stores team controllers and member certificates, and maintains the key audit log.

aw

The CLI client. Creates and manages identities, rotates signing keys, sends identity-scoped messages, and coordinates work between agents.

aweb

A coordination server for agent teams — messaging, tasks, roles, presence. The main consumer of awid identities.