identity#

identity in atproto separates "who you are" from "where you're hosted."

DIDs#

a DID (Decentralized Identifier) is your permanent identity. it looks like:

did:plc:xbtmt2zjwlrfegqvch7fboei

the DID never changes, even if you move to a different PDS. this is what makes account migration possible - your identity isn't tied to your host.

atproto primarily uses did:plc, where the PLC Directory (plc.directory) maintains a mapping from DIDs to their current metadata: signing keys, PDS location, and associated handles.

did:web is also supported, using DNS as the resolution mechanism. this gives you full control but requires maintaining infrastructure.

handles#

a handle is the human-readable name:

zzstoatzz.io
pfrazee.com

handles are DNS-based. you prove ownership by either:

• adding a DNS TXT record at _atproto.yourdomain.com
• serving a file at /.well-known/atproto-did

handles can change. they're aliases to DIDs, not identities themselves. if you lose a domain, you lose the handle but keep your DID and all your data.

resolution#

to find a user:

1. resolve handle → DID (via DNS or well-known)
2. resolve DID → DID document (via PLC directory)
3. DID document contains PDS endpoint
4. query PDS for data

# simplified resolution flow
handle = "zzstoatzz.io"
did = resolve_handle(handle)  # → did:plc:...
doc = resolve_did(did)        # → {service: [...], alsoKnownAs: [...]}
pds_url = doc["service"][0]["serviceEndpoint"]

caching#

DID resolution is expensive (HTTP calls to PLC directory). cache aggressively:

_did_cache: dict[str, tuple[str, float]] = {}
DID_CACHE_TTL = 3600  # 1 hour

async def get_did(handle: str) -> str:
    if handle in _did_cache:
        did, ts = _did_cache[handle]
        if time.time() - ts < DID_CACHE_TTL:
            return did
    did = await resolve_handle(handle)
    _did_cache[handle] = (did, time.time())
    return did

from at-me - caches DID resolutions with 1-hour TTL.

why this matters#

the separation of identity (DID) from location (PDS) and presentation (handle) is what enables the "connected clouds" model. you can:

• switch PDS providers without losing followers
• use your own domain as your identity
• maintain identity even if banned from specific applications

your identity is yours. hosting is a service you can change.