chadtmiller.com/monolith
An atproto PDS
OAuth: the account's own sessions and devices
An account sees the OAuth sessions it has given apps, and the browsers it
is signed in on through the authorization pages, and ends any of them,
with its own password session: four routes of the server's own, of no
lexicon and no NSID, as the admin's reads are (OPERATIONS.md, "The
admin's reads"). They are what the reference's account pages (/account)
do with a browser's cookies, which the server does not serve
(OAUTH.md), done with a token instead, so that the CLI and an agent can
do it. Their MCP tools and CLI commands are in COMMANDS.md, "The
account's OAuth sessions".
| Route | Method | Does |
|---|---|---|
/xrpc/_oauthSessions | GET | lists the account's OAuth sessions |
/xrpc/_oauthRevokeSession | POST | ends one |
/xrpc/_oauthDevices | GET | lists the devices the account is signed in on |
/xrpc/_oauthRevokeDevice | POST | signs it out of one |
A session here is an OAuth session as OAUTH.md keeps one ("The token
endpoint"), of either issuer: the atproto issuer's, or the MCP issuer's
(OAUTH-MCP.md). A device is a browser as OAUTH.md names one ("The
authorization page"), and an account is signed in on it as sign-in with
remember signs it in there (OAUTH.md, "The API"), or passkey-sign-in
(PASSKEYS.md).
Auth
Each route takes the token getAccountInviteCodes takes (LIMITS.md): an
access token of a session made with the account's password, of scope
com.atproto.access, as Authorization: Bearer. The token is checked
first, as for a method that needs one (PDS.md): one the server did not
give out, or past its exp, is refused as there. Then:
- no
Authorizationheader is401 AuthMissing; - an app password's session, a refresh token or a
Basicheader is400 InvalidToken; - an OAuth access token, sent as
DPoPwith a proof, is checked asOAUTH-SCOPES.mdchecks one on a method that needs a token, and then, whatever its scope,403 Forbidden,OAuth credentials are not supported for this endpoint, aslistAppPasswordsrefuses it.
At /mcp (OAUTH-MCP.md, "Tokens at the MCP endpoint"), a tool called
with no token is the sign-in challenge, as for any method that answers
401 AuthMissing; and one called with an MCP session's token is a tool
error, 403 Forbidden, as for a method that takes no OAuth token.
Note: the reference's account pages sign in with the account's password
alone, as the authorization page does (OAUTH.md, "sign-in"): an app,
holding an app password or an OAuth token, does not end the account's
other apps' sessions.
An account answers in each of its states as it answers listAppPasswords
and revokeAppPassword (LIFECYCLE.md, "Its own calls"): deactivated or
taken down, as an active one; deleted, with nothing to list, and nothing
to end.
Requests
Past the auth, each route checks, in this order:
- Its HTTP method:
400 InvalidRequest. - For
_oauthRevokeSessionand_oauthRevokeDevice, the body: one longer than 153600 bytes is413 PayloadTooLargeError, as for any method with a JSON input (LIMITS.md, "Request size"); thenContent-Type: application/json, and a JSON object withida string, else400 InvalidRequest. Its other properties are ignored.
Below PDS_MIN_FREE_BYTES (LIMITS.md, "Disk"), the revocations are not
refused: what they keep is the end of something, and an account short of
disk can still sign an app out.
The two lists take no parameters, and ignore any given. Each route answers
200 with Content-Type: application/json; charset=utf-8, costs a point
of global (LIMITS.md), and has its route, as _oauthSessions, in its
request line, its metrics and its span, as any request (OPERATIONS.md).
_oauthSessions
{"sessions": [{"id": "…", "clientId": "https://app.example/client-metadata.json", "issuer": "atproto", "scope": "atproto transition:generic", "createdAt": "2026-11-09T17:20:01.004Z", "updatedAt": "2026-11-09T17:35:02.120Z", "expiresAt": "2026-11-23T17:20:01.004Z"}]}
sessions holds every session of the token's account that has not ended
and is not past its end, the latest createdAt first, then by id; none
of another account's. Of each:
idis a string of lower case hexadecimal digits the server chooses that names the session for these routes, the same for as long as it lasts. It is none of its tokens or its code, and is taken as none of them anywhere.clientIdis its client'sclient_id.issuerisatprotofor a session ofOAUTH.md's issuer,mcpfor one ofOAUTH-MCP.md's.scopeis its scope as its last token answer gave it,include:scopes expanded (OAUTH-PERMISSION-SETS.md).createdAtis when the code grant started it,updatedAtits last token answer (itscreatedAtuntil it is refreshed), andexpiresAtwhen it ends however often it is refreshed: two weeks from its start, or for a confidential client asOAUTH-CLIENTS.mdsays.
Each time is a datetime as atproto/lexicon.md defines it, in UTC, with
milliseconds, as 2026-11-09T17:20:01.004Z.
_oauthRevokeSession
{id} ends the token's account's session of that id, as revocation ends
one (OAUTH.md, "Revocation"): from then on, its access token is 401 invalid_token on XRPC, and at /mcp the invalid_token challenge
(OAUTH-MCP.md); its refresh token, current or replaced, 400 invalid_grant; and _oauthSessions no longer lists it. It answers 200 {}, whether or not the account had a session of that id; a session of
another account's is left as it was. The clients the account approved stay
approved (OAUTH-CLIENTS.md), so that a client may sign it in again.
_oauthDevices
{"devices": [{"id": "…", "signedInAt": "2026-11-09T17:19:40.512Z", "loginRequired": false, "userAgent": "Mozilla/5.0 …", "ipAddress": "203.0.113.7"}]}
devices holds every device the token's account is signed in on, the
latest signedInAt first, then by id. Of each:
idis a string of lower case hexadecimal digits the server chooses that names the device for these routes, the same for as long as the device lasts. It is none of the device's cookies, and is taken as none of them anywhere.signedInAtis the account's last sign-in there, a datetime as above.loginRequiredis as the page's__sessionsgives it for the account on that device (OAUTH.md, "The authorization page"):trueonce that sign-in is more than seven days old.userAgentis theUser-Agentheader of that sign-in, its first 256 characters, andipAddressits client address (LIMITS.md, "Rate limits"); each is left out when the sign-in had none, or was kept before the server kept them.
_oauthRevokeDevice
{id} signs the token's account out of the device of that id, as
sign-out on that device would (OAUTH.md, "The API"): its page no longer
lists the account, a consent there for it needs a sign-in again, and
_oauthDevices no longer lists it. The other accounts signed in on it stay
signed in, and the sessions made through it stay, as OAUTH-MCP.md says of
sign-out. It answers 200 {}, whether or not the account was signed in
on a device of that id.
Durability
As OAUTH.md says ("Durability"): a session ended or a device signed out
of here, once answered, stays so after the server is killed, and the
userAgent and ipAddress of a sign-in are kept with it.
How it is checked
harness/checks/oauth-account.mjs, on the server alone: the reference
serves none of these routes, and its account pages' API is a browser's,
with its cookies. On accounts of their own, signed in through OAUTH.md's
flow as harness/checks/oauth.mjs signs them in, and with --commands
through OAUTH-MCP.md's too:
- Auth. Each route with no token, a token the server did not give out,
an app password's session, a refresh token, the admin's
Basic, and an OAuth access token with its proof: the errors above, and nothing listed or ended. With a password token: the other HTTP method; a revocation with no body, a body that is not JSON, with noid, or anidthat is not a string:400 InvalidRequest; one of 153601 bytes,413 PayloadTooLargeError. With--limits, belowPDS_MIN_FREE_BYTES, a session ended and a device signed out of here. - Sessions. An account with sessions of two clients, one refreshed:
_oauthSessionslists exactly those, each with its client, issuer, scope as its last token answer,createdAtandupdatedAtwithin a second of its code grant and its refresh, andexpiresAtits end; no session of another account; none ended by/oauth/revokeor by a replayed refresh token. Then_oauthRevokeSessionof one: itsgetSession401 invalid_token, its refresh400 invalid_grant, and the other still working; another account'sid, and anidno session has,200 {}, ending nothing. With--commands, an MCP session listed withissuermcp, and after its revocation,/mcptheinvalid_tokenchallenge. - Devices. A browser in which the account and a second account sign
in with
remember, with aUser-Agentof its own:_oauthDeviceslists that device, with the header, the client address andsignedInAtwithin a second of the sign-in; the sameidwhile the device lasts; no device the account signed in on withoutremember. Then_oauthRevokeDevice: the device's page lists the second account and not the first, and the sessions made through it still work. Everyidlisted, a session's or a device's, of lower case hexadecimal digits. - Lifecycle. With
--lifecycle, after each change of an account's state, its password token on the four routes, as the rows ofLIFECYCLE.md's "Its own calls" give them, on the server alone. - Commands. The tools and commands as
COMMANDS.mdchecks them. - Crashes. With
--crash-every, a session ended and a device signed out of here before a kill: after the restart, the session still ended, the device still not signed in, and a device still signed in listed with itsuserAgentandipAddress.