What are DIDs
W3C Decentralized Identifiers give agents a portable, cryptographic identity that works across services. Instead of an opaque token tied to one theAuth instance, an agent gets a DID likedid:key:z6Mk... backed by an Ed25519 keypair.
The agent proves its identity by signing a payload with its private key, and a verifier checks the signature against the agent’s public key. No shared secrets are needed. Note the current scope: theauth.did.verify() and theauth.did.verifyPresentation() look the public key up in the theAuth database, so they only verify DIDs generated by the same theAuth instance. A third party that only has a DID string cannot verify with these methods; see Sign and verify payloads.
DIDs are optional. Regular agent bearer tokens (
ta_...) work fine for single-service deployments. Use DIDs when agents need to prove identity across organizational boundaries.Two DID methods
theAuth supports two W3C DID methods:
Each agent can hold one DID: the record is keyed by agent ID, so calling
generateKey() or generateWeb() a second time for the same agent fails.
Generate a DID for an agent
- did:key
- did:web
Sign and verify payloads
An agent can sign a payload to prove it authored a request. The signature is an EdDSA JWT whoseiss is the agent’s DID and whose iat is set automatically:
verify looks up the stored public key for the DID you pass; it requires the DID argument and does not check that it matches the token’s iss, and it does not enforce an expiry unless the payload carries a standard exp claim. A verifier without database access must obtain the agent’s public JWK by its own means and call the lower-level verifyPayload(jws, publicKeyJwk), exported from @glinr/theauth. theauth.did.resolve() is not enough for that: for did:key it returns a document whose publicKeyJwk is only a placeholder ({ kty, crv } without x), because the key is not decoded from the identifier.
Verifiable presentations
A presentation is a signed JWT that bundles an agent’s identity with its capabilities. Use this when an agent needs to prove both who it is and what it can do.verifyPresentation returns { valid, issuer?, capabilities?, error? } with no agentId field (the agent ID is in the JWT’s sub and agentId claims, which the module does not return). It finds the public key by the JWT’s iss DID in the database, checks the signature and exp, and does not check the audience you set when creating it: if you rely on audience binding, verify the aud claim yourself. The capabilities are only assertions the agent signed, they are not checked against the agent’s actual permissions.
DID document structure
Every agent DID resolves to a W3C DID document:Retrieve a stored DID
Resolve any DID
resolve returns null for a malformed DID, a failed fetch, or an unsupported method.
The fields of a stored DID record (AgentDid):
Related
Verifiable credentials
Issue W3C Verifiable Credentials backed by agent DIDs.
Agent identity federation
Cross-service agent authentication using signed federation tokens.
Agent identity
Bearer token identity and the agent lifecycle managed by theAuth.
Standards alignment
IETF agentic JWT claim names and what theAuth emits today.