How it works

Three things happen over the life of a DNSid identity: an agent gets an identity, the agent identifies itself when it acts, and a service verifies that identity. Every step works against public DNS and HTTPS alone. No account, no central directory, and no DNSid service in the loop.

Register, sign, verify—each step has a dedicated walkthrough below.

1. An agent gets an identity

An identity is anchored to a domain the operator owns. Your domain vouches for your agent, and you operate the DNS and HTTPS endpoints behind it. This is the self-managed model.

Two keys do two jobs:

• The entity key belongs to the accountable entity. It signs the identity record and every lifecycle event.
• The operational key belongs to the agent. It signs runtime requests and tokens, and it rotates as the agent changes.

Registering publishes three things on the domain:

1. A signed _dnsid TXT record, the identity record. It points to the JWKS, the status endpoint, and the lifecycle log, and carries the entity key’s signature.
2. A JWKS endpoint serving the agent’s public keys.
3. A status endpoint serving the live protocol state, ACTIVE at first.

The issuance is also written to the agent’s lifecycle log, signed by both keys, so neither party can create the binding alone. Give an agent an identity walks the record field by field.

2. The agent identifies itself

At runtime the agent proves its identity with no shared secret and no prior arrangement. Three shapes fit different counterparties:

• Native verification. A DNSid-aware receiver verifies the agent’s domain directly against its _dnsid record. Nothing extra changes hands.
• Signed requests. The agent signs each HTTP request with its operational key, using the DNSid profile of RFC 9421 HTTP Message Signatures. The key identifier names the signer’s domain, so the receiver knows which record to resolve. See Sign HTTP requests, or let the Claude Agent SDK plugin do it automatically.
• Signed JWTs. Where a receiver expects a bearer token, the SDKs’ JOSE profile mints a DNSid JWT signed with the operational key. The receiver checks it against the issuer domain’s published key.

Authenticate as an agent covers all three and when to use each.

3. A service verifies

Everything a verifier needs is published on the domain, so the same check works for any DNSid identity. The SDK VerifyDomain call:

1. Resolves the _dnsid TXT record.
2. Validates the record’s signature against the entity key.
3. Fetches the JWKS from the record’s key URL.
4. Fetches the status document and confirms the state is ACTIVE.
5. Replays the lifecycle log to confirm the current key chains back to the issuance.

Success returns a verified domain with its status and keys. Failure returns a typed error with a stable code and a transient flag, so policy can tell a revoked identity from a DNS timeout. A valid result proves who signed. Whether to trust that signer is the receiver’s decision, and receivers should restrict the domains they accept. Verify other agents walks the flow and the failure cases.

What changes over time

Operators rotate keys, retire agents, and revoke identities. Each change is a signed lifecycle event, and revocation also flips the status endpoint to REVOKED. Verifiers see it on their next check, within the DNS and status cache windows. Status & freshness covers propagation and hosting a status endpoint well.

Next steps

Give an agent an identityRegistration & identity-record lifecycle.

Authenticate as an agentSigning requests as an agent.

Verify other agentsResolution, status, and error handling.

Core conceptsThe vocabulary the three steps rely on.