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, “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: the authorization server), done with a token instead, so that the CLI and an agent can
do it. Their MCP tools and CLI commands are in Commands: every method as an MCP tool and a CLI command, “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: the authorization server keeps one (“The token
endpoint”), of either issuer: the atproto issuer’s, or the MCP issuer’s
(OAuth for MCP clients). A device is a browser as OAuth: the authorization server names one (“The
authorization page”), and an account is signed in on it as sign-in with
remember signs it in there (OAuth: the authorization server, “The API”), or passkey-sign-in
(Passkeys).
Each route takes the token getAccountInviteCodes takes (Limits): 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 (The PDS: accounts and their records): 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 as OAuth: access tokens on every method, and what scopes allow checks 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 for MCP clients, “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: the authorization server, “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 (Account lifecycle, “Its own calls”): deactivated or
taken down, as an active one; deleted, with nothing to list, and nothing
to end.
Requests
Section titled “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, “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, “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), and has its route, as _oauthSessions, in its
request line, its metrics and its span, as any request (Operations).
_oauthSessions
Section titled “_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 of OAuth: the authorization server’s issuer,mcpfor one of OAuth for MCP clients’s.scopeis its scope as its last token answer gave it,include:scopes expanded (OAuth: permission sets).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 as OAuth: web, native and confidential clients says.
Each time is a datetime as atproto's Lexicon spec defines it, in UTC, with
milliseconds, as 2026-11-09T17:20:01.004Z.
_oauthRevokeSession
Section titled “_oauthRevokeSession”{id} ends the token’s account’s session of that id, as revocation ends
one (OAuth: the authorization server, “Revocation”): from then on, its access token is 401 invalid_token on XRPC, and at /mcp the invalid_token challenge
(OAuth for MCP clients); 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: web, native and confidential clients), so that a client may sign it in again.
_oauthDevices
Section titled “_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: the authorization server, “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, “Rate limits”); each is left out when the sign-in had none, or was kept before the server kept them.
_oauthRevokeDevice
Section titled “_oauthRevokeDevice”{id} signs the token’s account out of the device of that id, as
sign-out on that device would (OAuth: the authorization server, “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 for MCP clients says of
sign-out. It answers 200 {}, whether or not the account was signed in
on a device of that id.
Durability
Section titled “Durability”As OAuth: the authorization server 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
Section titled “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: the authorization server’s
flow as harness/checks/oauth.mjs signs them in, and with --commands
through OAuth for MCP clients’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 of Account lifecycle’s “Its own calls” give them, on the server alone. - Commands. The tools and commands as Commands: every method as an MCP tool and a CLI command checks 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.