---
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](oauth.md)
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](node.md) 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](handshake.md) — 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](ops-dashboard.md)'s operator sign-in.

**That the hook-stamped local identity in [cred-delivery](cred-delivery.md) 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](index.md)'s note that the first non-public read is when
      this becomes load-bearing, and [abuse-notices](abuse-notices.md) 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](agent-accounts.md). 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](ownership.md) 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](spaces.md) 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

- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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](handshake.md) — 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](e-stop.md) 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](ops-dashboard.md)'s operator sign-in. A surface that
      would need an operator credential is not built rather than gated on a
      stand-in.
- [x] **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.
- [x] **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.
- [x] **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.
- [x] **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`.
- [x] **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.