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); 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 The PDS: accounts and their records.
The methods: com.atproto.server.refreshSession, deleteSession,
createAppPassword, listAppPasswords and revokeAppPassword.
Tokens
Section titled “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:<PDS_HOSTNAME> | 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,
Account lifecycle).
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
Section titled “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 The PDS: accounts and their records 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
refreshSessionordeleteSession.
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: access tokens on every method, and what scopes allow).
refreshSession
Section titled “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): {accessJwt, refreshJwt, did, handle, email, emailConfirmed, emailAuthFactor, active: true} (Email), 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), is 400 ExpiredToken. Refreshing with session S’s token:
-
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.
-
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.
-
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.
-
It answers a new access token and a refresh token whose
jtiis 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
Section titled “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
Section titled “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}:privilegedisfalseunless giventrue;createdAtis when it was made, a datetime as atproto's Lexicon spec defines; andpasswordis four groups of four characters, each a lower case letter or a digit 2 to 7, joined by-, asabcd-efgh-2345-ijkl, random. The password is answered only here.nameis any string, the empty one too. A name the account already has for an app password is500 InternalServerError, as the reference answers it, and makes none; of several at once with the same name, one is made. Only a session of scopecom.atproto.accessmay make one: an app password’s session is400 InvalidToken, whatever the input. An account has at most 50: a 51st is400 TooManyAppPasswords(Limits).listAppPasswordsanswers{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 are400 ExpiredTokenfrom then on, those of sessions refreshed from them too. Their access tokens work until they expire. It answers200with 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), which answer it 400 InvalidToken,
and requestEmailUpdate and updateEmail (Email). 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
Section titled “Durability”Sessions are kept as Durability 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
Section titled “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,
getSessionandcreateRecord, given a refresh token where an access token is wanted, an access token where a refresh token is, a token with itssubchanged or itsalgmadenone, a token never given out, or anAuthorizationheader with another scheme, in lower case, or of three words; and a session’s access token, whatever became of the session, ongetSession. - app passwords:
createAppPasswordwith names old and new, odd ones, andprivilegedor not, with a full session or an app password’s;listAppPasswords;revokeAppPasswordof a name the account has or not, or another account has;createSessionwith an app password, revoked or not, by handle, email or DID, in upper case, or another account’s. - races: several
refreshSessions at once with one token, which all succeed with tokens of one session; severalcreateAppPasswords 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 The PDS: accounts and their records says, tokens taken out.
Not compared:
- An
ExpiredTokenfor a token past itsexp: the harness does not wait two hours, nor ninety days, nor the end of an old refresh token’s grace. It checksexp - iatinstead. refreshSessionanddeleteSessionwith one token at once: which lands first is a race on both sides.- Which algorithm signs the tokens, and the
jtiitself.