Accounts
The server holds any number of accounts. Each has a DID, a did:plc the
server makes or a did:web the account moves in with (Moving an account between servers), a handle, an
email, an optional password, its own signing key, its own KEM key
(Spaces), and its own repository.
Each account’s data is kept apart from every other’s: what one account’s
writes, recovery or storage touch is that account’s alone.
Environment
Section titled “Environment”Besides PDS_PORT and PDS_DATA_DIR (The PDS: accounts and their records):
| Variable | Description |
|---|---|
PDS_HOSTNAME | the server’s hostname; the server’s DID is did:web:<hostname> |
PDS_PUBLIC_URL | the URL its DID documents name as the account’s PDS |
PDS_HANDLE_DOMAINS | the domains handles may end in, comma-separated, each with its leading dot, such as .test |
PDS_PLC_URL | the PLC directory it registers DIDs with |
PDS_PLC_ROTATION_KEY_HEX | its secp256k1 PLC rotation key, 32 bytes as hex |
PDS_RECOVERY_DID_KEY | optional: a did:key listed before the server’s own as a rotation key of every DID it creates |
describeServer answers did, availableUserDomains (the handle domains in
the order given), inviteCodeRequired, as PDS_INVITE_REQUIRED sets it
(Limits), and spacesAlpha: true (Spaces). The reference also
answers links and contact from its own configuration; the server may
leave them out, and the harness does not compare them.
createAccount
Section titled “createAccount”createAccount takes an optional bearer token, a service token by which
an account moves here from another server, checked before anything else
as Moving an account between servers says. It checks its input in this order and answers the
first error:
-
The input against the lexicon: a handle that is not a handle by atproto's Handle spec is
400 InvalidRequest, and so is any other lexicon error. Then aplcOpgiven is400 InvalidRequest: the server takes no operation made elsewhere. -
A password longer than 256 UTF-16 code units, as JavaScript counts a string’s length (a character beyond U+FFFF counts two), is
400 InvalidRequest. None is allowed, and an empty one is the same as none: an account without a password exists, but nocreateSessionlogs into it, and it keeps no email. Its email is not taken by it, nocreateSessionfinds it by that email, and its sessions’ answers leaveemailout. Its email must still pass the checks below, and must not be one another account has. -
A missing email is
400 InvalidRequest, and so is one that is not an address of this form. Emails are compared and kept in lower case.- A local part,
@, and a domain, with no spaces or quotes anywhere. - The local part is at most 64 characters: dot-separated runs of
letters (any script), digits and
!#$%&'*+/=?^_`{|}~-, with no dot first, last, or next to another. - The domain is two or more dot-separated labels, with no dot last:
each 1 to 63 letters (any script), digits or hyphens, not starting
with a hyphen. The last label is not all digits, so an IP address is
no domain, and neither is
[1.2.3.4].
The reference also refuses addresses at disposable-mail domains, from a list it keeps. The server need not, and the harness sends none.
- A local part,
-
The handle, lowercased:
- a top-level domain that atproto's Handle spec disallows, such as
.example, is400 InvalidHandle; - a handle not ending in one of
PDS_HANDLE_DOMAINSis400 UnsupportedDomain. Where it ends in more than one, the longest is its domain. Withdidgiven, such a handle is instead an external one, which must resolve to that DID (Identity, “Resolving a handle”), else it is400 InvalidRequest; the rules below do not apply to it; - the part before that domain must be one label, of 3 to 18 characters.
A dot in it, then a length outside that range, is
400 InvalidHandle; - a label in
data/reserved-handles.txtis400 HandleNotAvailable.
- a top-level domain that atproto's Handle spec disallows, such as
-
A handle another account has is
400 InvalidRequest, then an email another account has is400 InvalidRequest, both compared in lower case. -
didgiven, other than the token’s (Moving an account between servers), or with no token, is401 AuthenticationRequired; then adidthat is neither adid:plcnor adid:web(Moving an account between servers) is400 InvalidRequest, and one an account here has, in any state but deleted,400 AlreadyExists. -
An
inviteCodegiven, not empty, that is not an available code is400 InvalidInviteCode. WithPDS_INVITE_REQUIRED, the code is checked earlier instead, as Limits says.
An account made with did moves here from another server, and is made
otherwise than below: Moving an account between servers says how.
Two createAccounts at once with the same handle or email create one account
at most. Rate limits, the request’s size, and the free space on disk may
refuse it first (Limits).
The server then creates the account (if anything below fails, such as the
PLC directory refusing the operation, no account is made, and the answer is
500 InternalServerError):
- a new secp256k1 signing key, which signs every commit of its repository;
- a new P-256 KEM key (Spaces);
- a
did:plc, by the genesis operation atproto's `did:plc` Method Specification spec describes, posted toPDS_PLC_URL. It has:verificationMethods.atproto, the signing key’sdid:key, andverificationMethods.atproto_kem, the KEM key’s;rotationKeys,PDS_RECOVERY_DID_KEYif set, then the rotation key’sdid:key;alsoKnownAs,["at://<handle>"];services.atproto_pds,{type: "AtprotoPersonalDataServer", endpoint: PDS_PUBLIC_URL}.
- an empty repository, with its first commit.
It answers {handle, did, didDoc, accessJwt, refreshJwt}, where didDoc is
the DID document the directory serves for the DID. On the firehose it is
#identity with the handle, #account with active: true, a #commit of
the empty repository, then #sync, numbered after every event before them.
Sessions
Section titled “Sessions”createSession takes as identifier a handle, an email, or a DID, with
handles and emails compared in lower case. A wrong password, or an
identifier no account has, is 401 AuthenticationRequired, no sooner than
350 ms after the input was checked, as a success is (Limits). The
session and its tokens are the account’s. getSession answers {did, handle, email, emailConfirmed, emailAuthFactor, active: true}, and createSession the
same with accessJwt and refreshJwt, without didDoc: emailConfirmed
and emailAuthFactor are false until Email changes them, which also
says what createSession’s authFactorToken does. For an account created
without a password, email is left out of both. An account that is not
active answers active: false and its status instead (Account lifecycle).
What the tokens are, refreshing and ending a session, and app passwords,
which createSession also takes, are in Sessions.
Writes to another account
Section titled “Writes to another account”A write names its repository by repo. After the token and the input are
checked, a repo no account here has is 403 AccountNotFound, and one that
another account here has is 401 AuthenticationRequired, whatever else is
wrong with the write.
Queries
Section titled “Queries”describeRepo, getRecord, listRecords, getRepo and getLatestCommit
answer any account’s repository, by handle or DID. A handle in repo is
matched as it is given, not lowercased: as every handle here is lower case,
one with a capital letter names no account here.
This section is informative.
data/reserved-handles.txt is from @atproto/pds, MIT licensed, and
atproto's `did:plc` Method Specification spec from did-method-plc, MIT or Apache-2.0. The server
may refuse other handles it finds offensive; nothing checks that.