Skip to content

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”.

RouteMethodDoes
/xrpc/_oauthSessionsGETlists the account’s OAuth sessions
/xrpc/_oauthRevokeSessionPOSTends one
/xrpc/_oauthDevicesGETlists the devices the account is signed in on
/xrpc/_oauthRevokeDevicePOSTsigns 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 Authorization header is 401 AuthMissing;
  • an app password’s session, a refresh token or a Basic header is 400 InvalidToken;
  • an OAuth access token, sent as DPoP with 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, as listAppPasswords refuses 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.

Past the auth, each route checks, in this order:

  1. Its HTTP method: 400 InvalidRequest.
  2. For _oauthRevokeSession and _oauthRevokeDevice, the body: one longer than 153600 bytes is 413 PayloadTooLargeError, as for any method with a JSON input (Limits, “Request size”); then Content-Type: application/json, and a JSON object with id a string, else 400 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).

{"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:

  • id is 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.
  • clientId is its client’s client_id.
  • issuer is atproto for a session of OAuth: the authorization server’s issuer, mcp for one of OAuth for MCP clients’s.
  • scope is its scope as its last token answer gave it, include: scopes expanded (OAuth: permission sets).
  • createdAt is when the code grant started it, updatedAt its last token answer (its createdAt until it is refreshed), and expiresAt when 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.

{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.

{"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:

  • id is 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.
  • signedInAt is the account’s last sign-in there, a datetime as above.
  • loginRequired is as the page’s __sessions gives it for the account on that device (OAuth: the authorization server, “The authorization page”): true once that sign-in is more than seven days old.
  • userAgent is the User-Agent header of that sign-in, its first 256 characters, and ipAddress its client address (Limits, “Rate limits”); each is left out when the sign-in had none, or was kept before the server kept them.

{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.

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.

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 no id, or an id that is not a string: 400 InvalidRequest; one of 153601 bytes, 413 PayloadTooLargeError. With --limits, below PDS_MIN_FREE_BYTES, a session ended and a device signed out of here.
  • Sessions. An account with sessions of two clients, one refreshed: _oauthSessions lists exactly those, each with its client, issuer, scope as its last token answer, createdAt and updatedAt within a second of its code grant and its refresh, and expiresAt its end; no session of another account; none ended by /oauth/revoke or by a replayed refresh token. Then _oauthRevokeSession of one: its getSession 401 invalid_token, its refresh 400 invalid_grant, and the other still working; another account’s id, and an id no session has, 200 {}, ending nothing. With --commands, an MCP session listed with issuer mcp, and after its revocation, /mcp the invalid_token challenge.
  • Devices. A browser in which the account and a second account sign in with remember, with a User-Agent of its own: _oauthDevices lists that device, with the header, the client address and signedInAt within a second of the sign-in; the same id while the device lasts; no device the account signed in on without remember. Then _oauthRevokeDevice: the device’s page lists the second account and not the first, and the sessions made through it still work. Every id listed, 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 its userAgent and ipAddress.