# Sessions A session is a pair of tokens: an access token, sent as the bearer token of every call made for the account, and a refresh token, which makes new pairs and ends the session. `createAccount` and `createSession` start sessions (`ACCOUNTS.md`); this page says what the tokens are, how a session is refreshed and ended, and app passwords. What every method shares, and how the server is checked, is in [`PDS.md`](PDS.md). The methods: `com.atproto.server.refreshSession`, `deleteSession`, `createAppPassword`, `listAppPasswords` and `revokeAppPassword`. ## Tokens Both tokens are JWTs (RFC 7519), signed with a key only the server holds, and carry exactly these claims: | | Access token | Refresh token | | --- | --- | --- | | header `typ` | `at+jwt` | `refresh+jwt` | | `scope` | the session's scope, below | `com.atproto.refresh` | | `sub` | the account's DID | the account's DID | | `aud` | the server's DID, `did:web:` | the same | | `jti` | none | the session's id | | `iat` | when it was made, in seconds since the epoch | the same | | `exp` | `iat` + 7200 (two hours) | `iat` + 7776000 (90 days) | The server may choose the header's `alg`; the reference signs with HS256. A session's scope is `com.atproto.access` for a session made with the account's password, `com.atproto.appPass` for one made with an app password, and `com.atproto.appPassPrivileged` for one made with a privileged app password (and `com.atproto.takendown` for one a taken-down account made, `LIFECYCLE.md`). A refresh token's `jti` is a string the server makes, the same for every refresh token of one session (below), and different between sessions. *Note:* clients read the tokens: Bluesky's app decodes the access token to read its `exp`, to know when to refresh, and its `scope`, to know an app password's session. ### Which token where Every method that takes a token, other than `refreshSession` and `deleteSession`, takes an access token; those two take a refresh token. The server checks the token before the input, as `PDS.md` says of writes. A bearer token is refused with `400 InvalidToken` when: - it is not a JWT the server signed, including one whose claims were changed after it was signed, and one whose header says `alg: none`; - it is a refresh token sent where an access token is wanted, or an access token sent to `refreshSession` or `deleteSession`. An access token is not checked against any session: it works until its `exp`, whatever happens to the session it came from. It still works after `deleteSession` ends that session, after `refreshSession` replaces it, and after the app password it was made with is revoked. A token past its `exp` is `400 ExpiredToken`, but one of the wrong kind for the method is `400 InvalidToken` first, expired or not. `deleteSession` takes a refresh token past its `exp` all the same, and ends its session. The `Authorization` header's scheme is matched without regard to case (`bearer` is `Bearer`). A header that is not two words separated by one space, or whose scheme is not `Bearer`, `Basic` or `DPoP`, is `400 InvalidToken`. `refreshSession` and `deleteSession` take only `Bearer`: a `Basic` header is `401 AuthMissing` there, as if there were none, and so is a `DPoP` header. Elsewhere a `Basic` header is `400 InvalidToken`. `DPoP` is OAuth's: every method that takes a token takes an OAuth access token with it (`OAUTH-SCOPES.md`). ## refreshSession `refreshSession` is a procedure with no input, called by `POST` with the refresh token as the bearer token. A request body is `400 InvalidRequest`, after the token is checked. It answers what `createSession` answers for the account (`ACCOUNTS.md`): `{accessJwt, refreshJwt, did, handle, email, emailConfirmed, emailAuthFactor, active: true}` (`EMAIL.md`), with no `didDoc`, and without `email` for an account created without a password. The new tokens have the session's scope: a session made with an app password stays one. The server keeps each session it gave out: its account, the app password it was made with if any, when it expires, and its successor, none at first. A refresh token whose session the server does not keep, as after `deleteSession`, or once the server dropped it as expired or past the account's 100 sessions (`LIMITS.md`), is `400 ExpiredToken`. Refreshing with session *S*'s token: 1. If *S* has no successor, the server makes a new session id *N*, and *S*'s successor is *N*. If it has one, that is *N*. 2. *S* now expires two hours from now, or when it did, whichever is sooner: the old refresh token keeps working for two hours after it is first used. *Note:* so two clients that share a refresh token may both refresh. 3. A session *N* is kept, with *S*'s account and app password, expiring 90 days from now, unless one with that id is kept already. 4. It answers a new access token and a refresh token whose `jti` is *N*. So refreshing with the same token again within those two hours answers a refresh token of the same session as the first time, and with the newest token, a new one. Refreshes at once with the same token all succeed, and all answer tokens of the same session. Where step 3 finds *N* gone, because `deleteSession` ended it, it is kept again: the old token's grace brings it back. ## deleteSession `deleteSession` is a procedure with no input and no output, called by `POST` with the refresh token as the bearer token. A request body is `400 InvalidRequest`, after the token is checked. The server stops keeping the session the token's `jti` names, and answers `200` with an empty body, whether or not it kept it. It ends that session alone: its successor, if it has one, and every other session carry on, and its access tokens work until they expire. ## App passwords An app password is a password for logging in to one account, with a name, made by the account itself, and revocable on its own. Each is kept with its name, a hash of it, when it was made, and whether it is privileged. - **`createAppPassword`** `{name, privileged?}` makes one, and answers `{name, password, createdAt, privileged}`: `privileged` is `false` unless given `true`; `createdAt` is when it was made, a datetime as `atproto/lexicon.md` defines; and `password` is four groups of four characters, each a lower case letter or a digit 2 to 7, joined by `-`, as `abcd-efgh-2345-ijkl`, random. The password is answered only here. `name` is any string, the empty one too. A name the account already has for an app password is `500 InternalServerError`, as the reference answers it, and makes none; of several at once with the same name, one is made. Only a session of scope `com.atproto.access` may make one: an app password's session is `400 InvalidToken`, whatever the input. An account has at most 50: a 51st is `400 TooManyAppPasswords` (`LIMITS.md`). - **`listAppPasswords`** answers `{passwords}`, the account's app passwords, newest first, each `{name, createdAt, privileged}`, as created. - **`revokeAppPassword`** `{name}` deletes the account's app password of that name, and stops keeping every session made with it, so their refresh tokens are `400 ExpiredToken` from then on, those of sessions refreshed from them too. Their access tokens work until they expire. It answers `200` with an empty body, whether or not the account had one of that name. It touches no other account's app passwords. `listAppPasswords` and `revokeAppPassword` take any access token of the account, an app password's session's too, which may revoke the app password it was made with. `createSession` takes an app password where it takes the account's password, by handle, email or DID, exactly as given: in upper case, or without its dashes, it is wrong. An account created without a password has none to log in with, but may make app passwords with its first session, and logs in with them by handle or DID; it keeps no email, so not by email. A session made with an app password, privileged or not, answers as any other, and may do what the account's own sessions do, but for `createAppPassword` and `getAccountInviteCodes` (`LIMITS.md`), which answer it `400 InvalidToken`, and `requestEmailUpdate` and `updateEmail` (`EMAIL.md`). It may change the account's handle with `updateHandle`, as the reference's may. One thing the reference does is a fault, and the server does not copy it. A session made with an app password named `""` becomes, when it is refreshed, a full session of scope `com.atproto.access`, which may make app passwords, and revoking that app password does not end it or the sessions refreshed from it. The server keeps such a session an app password's session, as above. *Note:* the harness makes, lists and revokes app passwords named `""`, but does not log in with one. ## Durability Sessions are kept as `DURABILITY.md` says: a session the server answered, the refresh that answered it, and its end by `deleteSession` or `revokeAppPassword`, all survive the server being killed. So does each app password and its revocation. ## How it is checked `harness/compare.mjs` keeps, for each account, the sessions it has had on each side, and each step picks one: - **refreshSession** with a session's refresh token, current or replaced, ended or not, on both sides, compared; a new session it answers joins the account's. - **deleteSession** with a session's refresh token, compared. - **wrong tokens:** each method of this page, `getSession` and `createRecord`, given a refresh token where an access token is wanted, an access token where a refresh token is, a token with its `sub` changed or its `alg` made `none`, a token never given out, or an `Authorization` header with another scheme, in lower case, or of three words; and a session's access token, whatever became of the session, on `getSession`. - **app passwords:** `createAppPassword` with names old and new, odd ones, and `privileged` or not, with a full session or an app password's; `listAppPasswords`; `revokeAppPassword` of a name the account has or not, or another account has; `createSession` with an app password, revoked or not, by handle, email or DID, in upper case, or another account's. - **races:** several `refreshSession`s at once with one token, which all succeed with tokens of one session; several `createAppPassword`s at once with one name, of which one makes it. - **crashes:** after each restart, some of every account's sessions are refreshed and its app passwords listed, compared with the reference, which was not killed. Every session's tokens the harness uses are decoded and held to the table above, as the reference's are: the header's `typ`, and the claims, with the DIDs named alike and times taken out. `exp - iat` must be exactly as above, and for tokens `refreshSession` or `createSession` with an app password answered, `iat` within a second of when the request was sent and answered. A refresh token's `jti` is named on each side by the order the harness first saw it, so the sessions refreshes answer must be the same ones on both sides, as above. Each app password must be of the form above; its `createdAt` must be a datetime within a second of the request, and the same in `listAppPasswords` as when created, and is taken out. The rest is compared as `PDS.md` says, tokens taken out. Not compared: - An `ExpiredToken` for a token past its `exp`: the harness does not wait two hours, nor ninety days, nor the end of an old refresh token's grace. It checks `exp - iat` instead. - `refreshSession` and `deleteSession` with one token at once: which lands first is a race on both sides. - Which algorithm signs the tokens, and the `jti` itself.