# 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 (`MIGRATION.md`), a handle, an email, an optional password, its own signing key, its own KEM key (`SPACES.md`), 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 Besides `PDS_PORT` and `PDS_DATA_DIR` (`PDS.md`): | Variable | Is | | --- | --- | | `PDS_HOSTNAME` | the server's hostname; the server's DID is `did:web:` | | `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.md`), and `spacesAlpha: true` (`SPACES.md`). 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 `createAccount` takes an optional bearer token, a service token by which an account moves here from another server, checked before anything else as `MIGRATION.md` says. It checks its input in this order and answers the first error: 1. The input against the lexicon: a handle that is not a handle by `atproto/handle.md` is `400 InvalidRequest`, and so is any other lexicon error. Then a `plcOp` given is `400 InvalidRequest`: the server takes no operation made elsewhere. 2. 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 no `createSession` logs into it, and it keeps no email. Its email is not taken by it, no `createSession` finds it by that email, and its sessions' answers leave `email` out. Its email must still pass the checks below, and must not be one another account has. 3. 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. 4. The handle, lowercased: - a top-level domain that `atproto/handle.md` disallows, such as `.example`, is `400 InvalidHandle`; - a handle not ending in one of `PDS_HANDLE_DOMAINS` is `400 UnsupportedDomain`. Where it ends in more than one, the longest is its domain. With `did` given, such a handle is instead an external one, which must resolve to that DID (`IDENTITY.md`, "Resolving a handle"), else it is `400 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.txt` is `400 HandleNotAvailable`. 5. A handle another account has is `400 InvalidRequest`, then an email another account has is `400 InvalidRequest`, both compared in lower case. 6. `did` given, other than the token's (`MIGRATION.md`), or with no token, is `401 AuthenticationRequired`; then a `did` that is neither a `did:plc` nor a `did:web` (`MIGRATION.md`) is `400 InvalidRequest`, and one an account here has, in any state but deleted, `400 AlreadyExists`. 7. An `inviteCode` given, not empty, that is not an available code is `400 InvalidInviteCode`. With `PDS_INVITE_REQUIRED`, the code is checked earlier instead, as `LIMITS.md` says. An account made with `did` moves here from another server, and is made otherwise than below: `MIGRATION.md` says how. Two `createAccount`s 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.md`). 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.md`); - a `did:plc`, by the genesis operation `atproto/did-plc.md` describes, posted to `PDS_PLC_URL`. It has: - `verificationMethods.atproto`, the signing key's `did:key`, and `verificationMethods.atproto_kem`, the KEM key's; - `rotationKeys`, `PDS_RECOVERY_DID_KEY` if set, then the rotation key's `did:key`; - `alsoKnownAs`, `["at://"]`; - `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 `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.md`). 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.md` 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 (`LIFECYCLE.md`). What the tokens are, refreshing and ending a session, and app passwords, which `createSession` also takes, are in `SESSIONS.md`. ## 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 `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. ## Data *This section is informative.* `data/reserved-handles.txt` is from `@atproto/pds`, MIT licensed, and `atproto/did-plc.md` from `did-method-plc`, MIT or Apache-2.0. The server may refuse other handles it finds offensive; nothing checks that.