---

id: auth-types title: Every credential this server accepts, and what each one may do status: open crates: [didbot-serve, didbot-pds] dependsOn: [agent-accounts, pds-writes] exitCriterion: > Every route the router serves names the credential types it accepts, a request carrying none is refused wherever the route needs a principal, and each accepted type is driven end to end by the conformance harness. #

auth-types #

This server accepts more than one kind of credential, and the question this epic answers is which kinds may exist, on what argument, and what a route does when a request carries none. It is deliberately not a policy engine and deliberately not a taxonomy written down twice.

Where the set lives #

Credential in crates/didbot-serve/src/auth.rs is the set, and there is no copy of it here or anywhere else. A list of credential kinds kept beside the code is a list that goes stale silently; the enum's variants carry their own documentation, routes.rs's xrpc_methods! invocations carry which route takes which, and both are compiled. Adding a kind, or changing what a route accepts, is an edit to one of those two places and to nothing else.

What this epic decides, which no enum can say:

Which questions a credential kind exists to answer. oauth builds one credential and the server that issues it. This epic is the other question: what this server does about every caller that is not holding one. A server implementing only OAuth still has to answer the client that arrives with a credential kind it does not accept, and it has to answer in a way that says so — hence a named-but-disabled scheme answering "recognised, not accepted" rather than a bare 401, which is a decision about who may talk to this server rather than a detail.

That a kind is added only when no existing kind fits the caller. The agent token was the worked example and is now the counter-example. It was added because a session token meant a machine holding a human credential shape — but what made that shape human was the password, not the session. Replace the password with the node attestation node already establishes and the rest of the session fits exactly: rotation, expiry, a refresh family, and reuse detection that revokes the family on replay. All of that is written and none of it exists on the bespoke token, which now also mints third-party authorization codes through bot.did.approveAuthorization.

• Take a session by attestation, and retire the agent token. One new way to take a session, and three gaps close with it: a year-long expiry, one live token per account, and no rotation route at all. Bind what the claim is for, not merely who is making it — a claim that names no subject is replayable against another account, which is the lesson the instance-identity work already learned about audience.

That there is no operator credential, and that this is load-bearing. A server learns which DID operates it by reading bot.did.operator out of the operator's own repository — see handshake — a mechanism whose whole point is that no operator credential ever reaches a PDS. So a surface that would need one is not built rather than gated on a stand-in, account-lifecycle mutations are self-service or nothing, and a closed disclosure route is closed to everyone alike. Proving control of the operator DID to this server is ops-dashboard's operator sign-in.

That the hook-stamped local identity in cred-delivery is not a credential here and must not become one. It says which agent is making a tool call. It is not presented over the wire and it authenticates nothing to this server.

• Accept another service's token on this server's own routes. This server mints service-auth tokens and proxies with them, and accepts none. Presented::Disabled("ServiceAuth") reserves the scheme name so a caller presenting one is told "recognised, not accepted" — see index's note that the first non-public read is when this becomes load-bearing, and abuse-notices for a caller that is a stranger's service rather than our own. The shape is the XRPC spec's "Inter-Service Authentication": an aud naming this server's DID and service, and an lxm naming the route.
• Per-principal rate limits. Not built.

The write surface, and the credential that unlocked it #

The write surface is no longer open. A write to a repository takes a credential that speaks for that account, and the authenticated DID is checked against the repository the request names — ApiError::repo_mismatch (403 RepoMismatch) is what a credential for one account gets for trying to write another's, an invariant rather than a policy knob.

Which credential each route takes is not written down here. auth::ROUTE_CREDENTIALS is built from the same declaration as the router, so a route cannot be served without an entry and an entry cannot disagree with what runs. A list in this file could, and would.

Getting there needed a credential a harness client could carry: it writes an agent's records and memories automatically, with no person at a login screen and no operator minting an app password for it, so an app-password session was the wrong vehicle — building it would have meant a machine holding a human credential shape for a caller that is never human. What it got was a bearer token, minted once at provisioning, bound to one DID, with an expiry and no rotation: didbot_pds::credential — Credential::AccountToken on the HTTP side. Provisioner::provision issues one automatically, durable in the write-ahead log (pds.layout bumped to 3), returned once as accountToken in createAccount's response body. A client carries it the same way it already carries the DID, and the conformance suite proves the whole path: client and server agreeing on a credential none of them minted by hand. That is what exists, not what should: the session taken by attestation above is what replaces it, and the argument for that swap is there rather than repeated here.

This is deliberately not an app-password session, not OAuth, and not inter-service auth.

The account-admin surface, and the mistake an over-broad label let happen #

Closing com.atproto.repo.* left bot.did.* — this server's own account-admin surface — open, on the reasoning that provisioning's credential is the ProvisionRequest's attestation claim, checked inside the registry rather than at the HTTP layer. The mutations beside it inherited that label without inheriting the check, which is how a route that destroys an account came to answer an unauthenticated POST: one request, no session, and no enumeration even needed, because the reads handed out every DID for free.

The lesson is the label, not the route. A kind that means "no credential" and a kind enforced somewhere other than the HTTP layer must not share a name, or a reader cannot tell which one a route has without going and looking. Attestation is its own kind for that reason. See crates/didbot-serve/src/auth.rs's module documentation for the taxonomy this section only summarises, and each variant's own doc for what it enforces.

Account-lifecycle mutations are always credentialed, never toggleable. The credential is the acting agent's own, in one of two postures.

A mutation that names an account checks the credential against it. A harness client calls these automatically — the same shape that argued (wrongly) for no credential before — but by the time one fires, the account already has its own write credential, and that is exactly the caller these routes are reasonable to ask one from. An agent may end or toggle itself, and that is the whole of it: acting on another account would need a credential proving this deployment's operator, and there is deliberately no such credential.

A mutation that names no account acts on whichever account the presented credential authenticates as. That is what makes a pending authorization readable, approvable and declinable only by the agent it was addressed to: there is no account parameter for the credential to disagree with.

bot.did.hardDeleteAccount, which must not be self-service, consequently has no route at all — see agent-accounts. There is no netizen argument for letting a stranger delete an account, so this stays hard-locked regardless of the disclosure decision below.

Publish by default: the accountability argument, and why it is a principle rather than a note about a few routes #

The account-admin reads are disclosure, not mutation — they say which agents a deployment runs and what happened to them — and the decision for them is not "lock them like the mutations." It is Credential::Disclosure: public by default, narrowable per route by deployment configuration, and never widenable past public. auth::Disclosure carries one bool per route, every field defaulting true; a deployment may flip a field to false, and nothing may flip one back past true, because there is nothing wider than public to widen into — the same narrowing-only rule that governs every configuration tier below the operator's own repository.

The reasoning is not specific to those routes, and should be read as one this project applies wherever a "should this be public" question of this shape comes up again — not re-derived per route:

• What is being published is the accountability mechanism, not an incidental leak. ownership exists so a stranger can ask whether an agent traces to a responsible human. That question has no answer if the deployment being asked is also the one deciding whether to be asked. Publishing which agents exist and what happened to them — the roster and the ledger — is the same argument this project already makes for publishing what it is doing elsewhere: divergence from what was promised has to be a comparison somebody outside can make, or the promise is unverifiable. A fresh deployment therefore starts open, not closed-until-configured.
• The toggle exists because "private means federation off" is a real, legitimate posture. spaces names it for the deployment as a whole; per-route disclosure is the same choice at a smaller grain, for an operator running agents on behalf of people who would rather not have every account enumerable by a stranger. Per route rather than one switch: closing the ledger while leaving the roster open (or the reverse) is a plausible posture a single flag cannot express.
• Closing a route has to be visible, or the mechanism defeats itself. The threat this default resists is an operator who cannot be audited, and the configuration tier that closes a route is a tier an on-box attacker also reaches — closing listAccounts is exactly what that attacker would do to hide what a stranger needed to see. This cannot be prevented from the server alone, but it is made legible: a closed route answers DisclosureDisabled, never a 404 and never an empty list, so an outsider can tell "this server runs no agents" from "this server is not telling you" — two different facts, and only one of them is suspicious. An operator credential still reaches a closed route, so closing it narrows who may read it without narrowing who may audit it.

This closes the "state what stays open to everyone" item below for bot.did.*: public-by-accident is gone, and what remains public does so for a reason the table now states, not because nobody got to it. It is written as a decision for now, not a permanent property — the owner has said this surface will be revisited, likely with finer-grained scoping than per-route booleans, and plan/spaces.md's alternative posture is exactly the direction that revisit would move in.

com.atproto.*'s read surface is a separate question this epic does not answer. com.atproto.sync.* and the read half of com.atproto.repo.* are public because the protocol requires it: a relay crawls them and an appview indexes them, and a credential there means no relay indexes these agents and nothing they write reaches Bluesky, contradicting what this project says it does. Whether this deployment federates at all is the operator's decision, made and recorded — public on purpose, not by accident, and plan/spaces.md's "private means federation off" is what a deployment reaches for if it decides otherwise. /.well-known/did.json and /.well-known/atproto-did are public for a third, purely structural reason: a DID that needs a credential to resolve is not a DID. See crates/didbot-serve/src/auth.rs's "Why every public route is public" for all three reasons laid out together.

What a deletion does to a credential #

A credential that outlives the account it authenticates is a credential with nothing behind it. Registry::delete and Registry::hard_delete therefore end every one of them, through one call: the registry revokes the agent token it holds and then calls the hook Registry::set_account_revoke_hook registers, which didbot_serve::app_with_repos wires to the stores that live beside the router — the account's OAuth grants and its unredeemed authorization codes.

The hook is the shape Estop::set_revoke_hook already uses, and for the same reason: the type that knows an account is going has no way to reach the stores that authenticate it, and a registry that held them would be holding the router's state. Wired in app_with_repos rather than left to whoever built an AuthState, so every router this crate builds has it.

A decommissioning ends a credential and a freeze does not. There is no path from decommissioned back to active — only a hard delete moves an account on from it — so a credential left alive there would authenticate an account that can never write again, and every read a decommissioned account still serves is public and needs no credential at all. A freeze is the reversible state: an account that will be unfrozen keeps what it holds, or lifting the freeze would mean re-provisioning it.

Done #

• Take the account off the header. REPO_HEADER is deleted. The repository an upload lands in comes solely from the credential the request presented, with no second field to disagree with it.
• Require an agent's own credential on the repo write surface itself. A repo write authenticates as the account it writes to; see "The write surface, and the credential that unlocked it" above for what that credential is and why it is not an app-password session, and auth::ROUTE_CREDENTIALS for what each route takes today.
• Decide the set, then refuse everything else by name. The set is Credential in crates/didbot-serve/src/auth.rs, and it is not restated here. A scheme this server does not define and a scheme it names but does not accept are told apart on the wire: Presented::Unrecognized is AuthenticationRequired (401), Presented::Disabled is SchemeDisabled (403), a client-visible difference and not only an internal one.
• One extractor, and a per-route declaration of what it accepts. routes.rs's xrpc_methods! macro is that declaration: it builds the router, the NSID lists and auth::ROUTE_CREDENTIALS out of one set of entries, and an entry that names no credential does not parse. So a route without one is a compile error rather than a route that defaults open, and a declaration cannot outlive the route it names, because deleting the entry deletes both. every_served_route_has_a_credential is what stops somebody mounting an XRPC route outside the macro.
• Require a proof on creation. bot.did.createAccount refuses a creator with no proof. tree::proof::prove checks a session, a JWT against the creator's bot.did.credential records, or an ID token against the issuer they name, refuses a creator that is not active or is locked, and makes the creator the child's parent. crates/didbot-serve/tests/tree.rs drives it through the router.
• Mint service-auth tokens, and proxy with them. com.atproto.server.getServiceAuth signs the XRPC spec's inter-service JWT with the account's #atproto key, within the reference PDS's limits, and an XRPC call this server does not serve, carrying atproto-proxy, is forwarded with one. Both take the account's own agent token, or an OAuth grant whose rpc: scope reaches the service. crates/didbot-serve/tests/service_auth.rs drives both against a stand-in service that checks the token.
• Answer the app-password question. There are none. No account here has a person to hold one, an agent's credential comes from provisioning and a third-party app's from OAuth, and a client that speaks only com.atproto.server.createSession therefore has no way to act as an agent — which is the custody rule, not a gap in it.
• Say what an operator credential is: there is not one. No scheme this server accepts authenticates an operator, and none should. A server learns which DID operates it by reading bot.did.operator out of the operator's own repository — see handshake — a mechanism whose whole point is that no operator credential ever reaches a PDS. A header this server could compare would be one it holds, which is the thing the handshake makes unnecessary. The declarations carry the consequences: every account-lifecycle mutation is self-service (auth::require_self, an agent token naming the account the request names), a closed disclosure route is closed to everyone, and e-stop is thrown behind the operator sign-in, from the dashboard route or didbot estop. Proving control of the operator DID to this server is ops-dashboard's operator sign-in. A surface that would need an operator credential is not built rather than gated on a stand-in.
• State what stays open to everyone. Decided and written down in auth.rs's module doc, under "Why every public route is public": three separate reasons, not one — protocol-required, so a relay can index these agents; structurally required, since a DID or a credential that needs a credential to reach is incoherent; and public-by-default-and-toggleable (see "Publish by default" above) for the account-admin reads that used to be public by accident. Which route is which is auth.rs's to say, not this file's. The write surface and the account-admin mutations are not open — see above.
• Credential the account-admin mutations. They take the acting agent's own credential — see "The account-admin surface, and the mistake an over-broad label let happen" above. Attestation is its own kind, so that gate is visible in the table rather than sharing a label that meant "no credential" everywhere else.
• Decide the account-admin reads, and build the toggle. They are Credential::Disclosure — public by default, closeable per route by auth::Disclosure, and a closed route answering DisclosureDisabled — for every caller alike, since no credential reaches past the toggle — rather than a 404 or an empty list. See "Publish by default" above for why the default is public and why the toggle exists anyway.
• The failure shapes, and the headers that go with them. AuthenticationRequired, ExpiredToken, InvalidToken and the new SchemeDisabled are in crates/didbot-serve/src/error.rs and auth.rs, each carrying WWW-Authenticate: Bearer where a client would act on it. A DPoP-bound token's own failures carry the DPoP scheme and, on RFC 9449 §9's nonce challenge, a DPoP-Nonce header -- auth.rs's refused_proof.
• A route that needs a principal and has none is a bug the tests can see. crates/didbot-serve/src/tests/mod.rs and auth.rs's own suite cover the no-credential case route by route, and crates/didbot/tests/conformance/wire.rs drives it, plus the cross-account RepoMismatch case, through the real router and the vendored lexicon documents. Which routes those are is auth::ROUTE_CREDENTIALS's to say: the_credential_table_is_exactly_the_served_routes, every_declared_credential_names_a_live_route and every_served_route_has_a_credential are what keep the table, the router and the source in agreement.

Left open, on purpose: accepting another service's token, per-principal rate limits, and the caller-facing app-password lexicon methods.