# Passkeys An account may sign in on the authorization page (`OAUTH.md`) with a passkey instead of its password: a WebAuthn credential (`webauthn/`) that a browser, a phone or a password manager keeps, which proves it is there by signing what the server asks. The account adds one through a link it asks for with its password session, opened in a browser; lists and removes them with the same session. The reference PDS has no passkeys: everything here is the server's own, and checked against this page alone. | Route | Method | Does | | --- | --- | --- | | `/xrpc/_passkeyList` | `GET` | lists the account's passkeys | | `/xrpc/_passkeyAdd` | `POST` | makes a link that adds one | | `/xrpc/_passkeyRemove` | `POST` | removes one | | `/oauth/passkey` | `GET` | the page the link opens, which adds the passkey | The first three are routes of the server's own, of no lexicon and no NSID, as `OAUTH-ACCOUNT.md`'s are; their MCP tools and CLI commands are in `COMMANDS.md`, "The account's passkeys". The page and its API call, `passkey-register`, and the authorization page's two calls that sign in with a passkey, `passkey-options` and `passkey-sign-in`, are below. What each page shows a person is in `OAUTH-PAGES.md`. ## Sources *This section is informative.* | File | Is | Licence | | --- | --- | --- | | `webauthn/webauthn-3.md` | Web Authentication, Level 3: registering a credential (§7.1), verifying an assertion (§7.2), authenticator data (§6.1), attested credential data (§6.5.1), `none` attestation (§8.7), and test vectors (§16) | W3C Software and Document License, `webauthn/LICENSE-W3C.md` | | `webauthn/rfc8949.txt` | CBOR | IETF Trust (BCP 78) | | `webauthn/rfc9052.txt` | COSE structures: the COSE_Key (§7) | IETF Trust | | `webauthn/rfc9053.txt` | COSE algorithms: ES256 (§2.1), EC2 keys (§7.1) | IETF Trust | | `webauthn/rfc8230.txt` | RSA in COSE: RSA keys (§4) and their sizes (§6.1) | IETF Trust | | `webauthn/rfc8812.txt` | COSE registrations for WebAuthn: RS256 (§2) | IETF Trust | | `webauthn/rfc8017.txt` | PKCS #1: RSASSA-PKCS1-v1_5 (§8.2) | IETF Trust | `webauthn/README.md` says where each is from. In WebAuthn's words, the server is the Relying Party, a passkey a client-side discoverable public key credential, its record on the server a credential record, and the link's page and the authorization page the scripts that run its registration and authentication ceremonies. ## The relying party - **RP ID.** The host of the issuer (`OAUTH.md`, "The issuer"), without its port: `pds.example.com` for `https://pds.example.com`, `localhost` for `http://localhost:2583`. *Note:* a browser takes no IP address as an RP ID, so with an issuer of `http://127.0.0.1:` the routes and checks below answer as said, but no browser makes or uses a passkey. A passkey is bound to the RP ID it was made for: once `PDS_PUBLIC_URL` names another host, browsers no longer offer the passkeys made before, which the server still keeps until they are removed. - **Origin.** The issuer, exactly: scheme, host and port. - **Algorithms.** ES256: ECDSA on P-256 with SHA-256, COSE algorithm `-7` (`webauthn/rfc9053.txt`, §2.1); and RS256: RSASSA-PKCS1-v1_5 with SHA-256, COSE algorithm `-257` (`webauthn/rfc8812.txt`, §2), with a modulus of 2048 to 4096 bits. A browser asks an authenticator for ES256 first. *Note:* the two every authenticator is asked to support, so that none fails to make a passkey for want of one; Chromium says so of a page that offers fewer. - **User handle.** Each account has one: 32 bytes, the HMAC-SHA-256 of its DID under a key of 32 random bytes the server makes once and keeps, so the same for all its links and passkeys, whatever happens to the account, and made by nothing outside the server. It is not the account's DID, and shows nothing of it (`webauthn/webauthn-3.md`, §14.6.1). - **Encoding.** Every byte string in JSON here, a credential ID, a challenge, a user handle and each of a credential's members that WebAuthn types `Base64URLString`, is base64url without padding (RFC 4648, §5). A string sent to the server that is not is refused as the step reading it says. An account has at most 20 passkeys. ## Auth `_passkeyList`, `_passkeyAdd` and `_passkeyRemove` take the token `OAUTH-ACCOUNT.md`'s routes take, and refuse the others as they do (`OAUTH-ACCOUNT.md`, "Auth"): no `Authorization` header is `401 AuthMissing`; an app password's session, a refresh token or a `Basic` header `400 InvalidToken`; an OAuth access token `403 Forbidden`; and at `/mcp`, with no token, the sign-in challenge, and with an MCP session's token the tool error `403 Forbidden`. *Note:* a passkey signs in as the password does; what may add one is what may change the password, the account's password session alone. ## Requests Past the auth, each route checks, in this order: 1. Its HTTP method: `400 InvalidRequest`. 2. For `_passkeyAdd`, the account's state: taken down is `401 AccountTakedown`, and deleted `403 AccountNotFound` (`LIFECYCLE.md`, "Its own calls"). 3. For `_passkeyAdd` and `_passkeyRemove`, the body: one longer than 153600 bytes is `413 PayloadTooLargeError`, as for any method with a JSON input (`LIMITS.md`, "Request size"); then `Content-Type: application/json`, and a JSON object with, for `_passkeyAdd`, `name` a string of 1 to 64 characters (Unicode code points), and for `_passkeyRemove`, `id` a string; else `400 InvalidRequest`. Their other properties are ignored. `_passkeyList` takes no parameters, and ignores any given. Each route answers `200` with `Content-Type: application/json; charset=utf-8`, costs a point of `global` (`LIMITS.md`), and has its route, as `_passkeyList`, in its `request` line, its metrics and its span, as any request (`OPERATIONS.md`). None is refused below `PDS_MIN_FREE_BYTES`: `_passkeyAdd` keeps nothing on disk, and `_passkeyRemove` keeps the end of something, as `OAUTH-ACCOUNT.md`'s revocations do. ## _passkeyList ```json {"passkeys": [{"id": "…", "name": "Laptop", "createdAt": "2026-11-14T09:02:11.500Z", "lastUsedAt": "2026-11-14T09:05:40.031Z", "backedUp": true}]} ``` `passkeys` holds every passkey of the token's account, the latest `createdAt` first, then by `id`; none of another account's. Of each: - `id` is its credential ID. - `name` is the name `_passkeyAdd` was given for it. - `createdAt` is when `passkey-register` added it, and `lastUsedAt` its last sign-in by `passkey-sign-in`, left out when it has none; each a datetime as `atproto/lexicon.md` defines it, in UTC, with milliseconds. - `backedUp` is the backup state (BS) its authenticator data last gave (`webauthn/webauthn-3.md`, §6.1.3). ## _passkeyAdd `{name}` makes a link that adds a passkey of that name to the token's account, and answers: ```json {"url": "https://pds.example.com/oauth/passkey?token=…", "expiresAt": "2026-11-14T09:17:11.500Z"} ``` An account that has 20 passkeys is `400 InvalidRequest`, and makes none. - `url` is `/oauth/passkey?token=`, where `` is 32 random bytes, base64url: the link. It is a secret: whoever opens it in time adds a passkey to the account. - `expiresAt` is 900 seconds from now, a datetime as above: the link ends then. The link holds the account, the name, and a challenge of 32 random bytes, the registration's. An account has one link at a time: a new one ends the one before, whose page and `passkey-register` then answer as for a link ended. A link is used once: the passkey it adds ends it. Links are held in memory alone ("Durability"). ## _passkeyRemove `{id}` removes the token's account's passkey of that credential ID: from then on, `passkey-sign-in` with it is refused, and `_passkeyList` no longer lists it. It answers `200 {}`, whether or not the account had a passkey of that `id`; a passkey of another account's is left as it was. The devices the passkey signed the account in on stay signed in, as the sessions made through them stay: `OAUTH-ACCOUNT.md`'s routes end those. ## The passkey page `GET /oauth/passkey?token=` is a navigation, and is refused otherwise, as the authorization page is (`OAUTH.md`, "The authorization page"): a `400` error page `invalid_request`. Its other methods are `404`. Then a `token` missing, or none of a link held, ended or past its time, or the link of an account taken down or deleted, is a `400` error page `invalid_request`. Otherwise the page answers `200`, `Cache-Control: no-store`, as `OAUTH-PAGES.md` builds a page ("How the pages are built"), with one statement, `window["__passkeyData"]=JSON.parse("…");`, of: - `account`: `{did, handle}`, and `name` and `picture` when the account has them, as `OAUTH.md` gives an account's (`OAUTH.md`, "The authorization page"). - `name`: the link's name. - `expiresAt`: when the link ends, as `_passkeyAdd` answered it. - `options`: the registration's options, `PublicKeyCredentialCreationOptions` in the JSON form `parseCreationOptionsFromJSON()` takes (`webauthn/webauthn-3.md`, §5.1.8), byte strings in base64url: | Member | Is | | --- | --- | | `rp` | `{id, name}`, both the RP ID | | `user` | `{id, name, displayName}`: the account's user handle, its handle, and its `name` when it has one, else its handle | | `challenge` | the link's challenge | | `pubKeyCredParams` | `[{"type": "public-key", "alg": -7}, {"type": "public-key", "alg": -257}]` | | `timeout` | `300000` | | `excludeCredentials` | each of the account's passkeys, as `{type: "public-key", id}`, with `transports` when it kept any | | `authenticatorSelection` | `{"residentKey": "required", "requireResidentKey": true, "userVerification": "required"}` | | `attestation` | `"none"` | The page sets the `csrf-token` cookie as the authorization page does, and no device cookies. Loading it keeps nothing and ends nothing: it may be loaded again while the link holds. It costs no rate limit, and is not refused below `PDS_MIN_FREE_BYTES`. ## passkey-register The passkey page's script calls `POST /@atproto/oauth-provider/~api/passkey-register` with `{credential}`, checked as `OAUTH.md` checks the API's calls ("The API"), but for the `Referer`: the issuer's origin, path `/oauth/passkey`, and a `token` query parameter. The call is then for that link. A `passkey-register` with the authorization page's `Referer`, and any other endpoint with the passkey page's, is `400 invalid_request`. `credential` is what the browser's `navigator.credentials.create()` gave, as its `toJSON()` gives it (`RegistrationResponseJSON`, `webauthn/webauthn-3.md`, §5.1). The call checks, as §7.1 does, in this order, each failure `400` with `{"error", "error_description"}`: 1. **The link**: held, not ended, not past its time, and its account neither taken down nor deleted: else `access_denied`. A link adds one passkey: of two calls through it at once that would each add one, one does, and the other is `access_denied`. Every check after this one fails with `invalid_request`. 2. **Its form**: `credential` an object with `id` and `rawId` the same string, base64url; `type` `public-key`; and `response` an object with `clientDataJSON` and `attestationObject` base64url strings, and `transports`, when present, an array of strings. Its other members are ignored. 3. **The client data** (§7.1, steps 5 to 11): `clientDataJSON` UTF-8, a leading byte order mark dropped, a JSON object whose `type` is `webauthn.create`, whose `challenge` is the link's, base64url, whose `origin` is the origin above, whose `crossOrigin` is absent or `false`, and which has no `topOrigin`. Its other members are ignored. 4. **The attestation object** (§7.1, steps 13 and 19 to 24): `attestationObject` one CBOR item (`webauthn/rfc8949.txt`), with nothing after it: a map of exactly `fmt`, `attStmt` and `authData`; `fmt` `none`, and `attStmt` an empty map (§8.7); `authData` a byte string. 5. **The authenticator data** (§6.1, §7.1, steps 14 to 18): `rpIdHash` the SHA-256 of the RP ID; UP set; UV set; BS set only with BE; AT set; then the attested credential data (§6.5.1): `aaguid`, 16 bytes; `credentialIdLength`, 2 bytes, big-endian; `credentialId`, of that many bytes, at most 1023, and the bytes `rawId` names; and `credentialPublicKey`, one CBOR item, a COSE_Key (`webauthn/rfc9052.txt`, §7) of one of the algorithms above: for ES256, a map of exactly `1` (kty) `2` (EC2), `3` (alg) `-7`, `-1` (crv) `1` (P-256), and `-2` (x) and `-3` (y) byte strings of 32 bytes each, a point on P-256; for RS256, a map of exactly `1` (kty) `3` (RSA), `3` (alg) `-257`, `-1` (n) a byte string of 256 to 512 bytes whose first is not zero, and `-2` (e) a byte string of 1 to 8 bytes whose first is not zero, an odd number of at least 3 (`webauthn/rfc8230.txt`, §4). With ED set, one CBOR map follows it, the extensions, which are ignored; with ED clear, nothing does. Nothing follows that. 6. **New**: no account has a passkey of that credential ID (§7.1, step 26). Below `PDS_MIN_FREE_BYTES`, a call that passes these is `507 {"error": "temporarily_unavailable", "error_description"}`, keeping nothing, and the link holds. Otherwise the passkey is the account's: its credential ID; its public key; its signature count, BE and BS, as the authenticator data gave them; its `transports`, those of `usb`, `nfc`, `ble`, `smart-card`, `hybrid` and `internal` the credential gave, each once, in the order given; the link's name; and `createdAt` now. The link ends, and the call answers `200 {}`. ## Signing in The authorization page signs an account in with a passkey by a challenge its device holds, which the page's own statement gives it as it loads, or `passkey-options` gives it at once, and then `passkey-sign-in`. The calls are checked as `OAUTH.md` checks every call of the API ("The API"), the authorization page's `Referer` among them. Neither needs the request the `Referer` names to be held, as `sign-in` does not. A device's **challenge** is 32 random bytes, held for the device (`OAUTH.md`, "Devices") for 300 seconds. A device holds one challenge: a new one replaces it. Challenges are held in memory alone ("Durability"). The **options** of a challenge are the authentication's, `PublicKeyCredentialRequestOptions` in the JSON form `parseRequestOptionsFromJSON()` takes (`webauthn/webauthn-3.md`, §5.1.9): ```json {"challenge": "…", "rpId": "pds.example.com", "timeout": 300000, "userVerification": "required", "allowCredentials": []} ``` `allowCredentials` is empty: the browser offers the passkeys it has for the RP ID, and the one chosen names its account (§7.2, step 6). ### The page's options The authorization page, when it answers `200` (`OAUTH.md`, "The authorization page"), gives the device it answers a new challenge, and has one statement more, `window["__passkeyOptions"]=JSON.parse("…");`, of its options. The page offers the device's passkeys in its identifier field's autofill with them, as it appears, so it calls nothing to have them (`OAUTH-PAGES.md`, "Sign in"). The page is not refused below `PDS_MIN_FREE_BYTES` for it: a challenge is kept in memory alone. ### passkey-options `passkey-options` `{}` gives the call's device a new challenge, and answers `{options}`, its options. A call that names no device, with no device cookies or ones the server did not set, is `400 invalid_request`. ### passkey-sign-in `passkey-sign-in` `{locale, credential, remember?}`: `locale` as `sign-in` takes it, `remember` a boolean, and `credential` what the browser's `navigator.credentials.get()` gave, as its `toJSON()` gives it (`AuthenticationResponseJSON`, §5.1). It checks, as §7.2 does, in this order, each failure `400 invalid_request`: 1. **The challenge**: the call's device holds one, within its 300 seconds. It is spent now, whatever follows: a device's challenge signs in once, or fails once. 2. **Its form**: `credential` an object with `id` and `rawId` the same string, base64url; `type` `public-key`; and `response` an object with `clientDataJSON`, `authenticatorData`, `signature` and `userHandle`, base64url strings. Its other members are ignored. 3. **The passkey** (§7.2, step 6): a passkey of the credential ID `rawId` names, whose account's user handle is `userHandle`. 4. **The client data** (§7.2, steps 8 to 14): as `passkey-register`'s, but `type` `webauthn.get`, and `challenge` the device's. 5. **The authenticator data** (§7.2, steps 15 to 19): at least 37 bytes; `rpIdHash` the SHA-256 of the RP ID; UP set; UV set; BS set only with BE; BE as the passkey's; AT clear; with ED set, one CBOR map after the 37 bytes, ignored, and with it clear, nothing. 6. **The signature** (§7.2, steps 20 and 21): `signature`, by the passkey's public key, over `authenticatorData` followed by the SHA-256 of `clientDataJSON`: for ES256, an ECDSA signature, DER-encoded, an `s` in the curve's upper half taken as in its lower; for RS256, an RSASSA-PKCS1-v1_5 signature with SHA-256, as many bytes as the modulus. 7. **The signature count** (§7.2, step 22): when the authenticator data's or the passkey's count is not zero, the authenticator data's is greater than the passkey's. *Note:* a count that did not grow is a sign the passkey was copied; the server refuses it rather than weigh it. 8. **The account**: one taken down is `400 invalid_request`, `Account was taken down`, as `sign-in` answers it (`LIFECYCLE.md`, "OAuth sessions"). A deactivated one signs in, as with its password. Below `PDS_MIN_FREE_BYTES`, a call that passes these is `507 {"error": "temporarily_unavailable", "error_description"}`, keeping nothing. Otherwise the passkey's signature count and BS are the authenticator data's, its `lastUsedAt` is now, and the account is signed in as `sign-in` signs it in (`OAUTH.md`, "The API"): with `remember: true`, or with `remember` left out when the account is already signed in on this device, on the device, its sign-in time there now, with its `User-Agent` and client address (`OAUTH-ACCOUNT.md`); otherwise not, and the answer has an `ephemeralToken` too. It answers `{account}`, as `sign-in` does. A passkey stands for both of the account's factors: with its email factor on (`EMAIL.md`), `passkey-sign-in` signs in with no code, and mails none. It costs no rate limit, as the API's other calls (`OAUTH.md`, "Rate limits"), and answers as soon as it is checked: it hashes no password, and names no identifier whose time could show anything. The account's `consent`, `reject` and redirect are then as after `sign-in`, for either issuer's request (`OAUTH-MCP.md`), which uses the same page. ## The account's states - `_passkeyList`, `_passkeyAdd` and `_passkeyRemove` answer in each of the account's states as `LIFECYCLE.md`'s "Its own calls" gives them. - A deactivation, a takedown, applied or lifted, and a change of email leave the passkeys as they were: a taken-down account's passkeys sign in again once the takedown is lifted. - A password reset (`EMAIL.md`, "resetPassword") removes every passkey of the account, and ends its link, as it ends what else whoever had its password may have left. - A deletion (`LIFECYCLE.md`, "deleteAccount") removes every passkey of the account and ends its link. ## Durability As `DURABILITY.md` says of every answered write: a passkey `passkey-register` added, its removal by `_passkeyRemove`, a password reset or a deletion, and each `passkey-sign-in`'s signature count, BS and `lastUsedAt`, with the sign-in on the device it made, survive the server being killed, and so does the key user handles are made with. A link and a challenge are held in memory alone: after a restart none is held, so the page of a link made before is the error page, its `passkey-register` `access_denied`, and a `passkey-sign-in` `400 invalid_request`, until a new link or challenge is made. ## How it is checked `harness/checks/passkeys.mjs`, on the server alone: the reference has no passkeys. Its authenticator is the harness's own, made with `node:crypto` as `webauthn/webauthn-3.md` describes one: a P-256 key for each passkey, and `clientDataJSON`, authenticator data and attestation objects written byte by byte, so that each can be made wrong in one way. Its pages are loaded and its API called as `harness/lib/oauth.mjs` does, with the issuer's origin. - **Auth.** Each of the three routes 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, made or removed. With a password token: the other HTTP method; `_passkeyAdd` and `_passkeyRemove` with no body, a body that is not JSON, with no `name` or `id`, a `name` of 0 and of 65 characters, and one of 64 characters of four bytes each, taken; one of 153601 bytes, `413 PayloadTooLargeError`. - **Adding.** `_passkeyAdd`: its `url` and `expiresAt` 900 seconds on, within a second. The page: `__passkeyData` as above, its `options` member by member, `user.id` the same 32 bytes for each of an account's links, before its first passkey and after, after a password reset and after a restart, of no other account's, and `excludeCredentials` the account's passkeys, compared as a set; at 20 passkeys, `_passkeyAdd` `400 InvalidRequest`; two `passkey-register`s through one link at once, one `200 {}` and the other `access_denied`, one passkey added; the navigation refused as the authorization page's is; a missing token, a token of no link, and the first link's after a second `_passkeyAdd`, each the error page. Then `passkey-register` with the harness's authenticator: `200 {}`, `_passkeyList` listing it with its name, `createdAt` within a second, no `lastUsedAt`, and `backedUp`, with BE and BS each set and clear; the link then ended, page and call. Refused, each with one thing wrong and nothing added, the link still holding but for the first: an ended link (`access_denied`); the credential's form; `type` `webauthn.get`; another challenge; another origin, and the issuer's with another port; `crossOrigin: true`; a `topOrigin`; a byte order mark, taken; another `rpIdHash`; UP clear; UV clear; BS without BE; AT clear; `fmt` `packed`; a non-empty `attStmt`; an attestation object with a fourth key, and with a byte after it; a credential ID other than `rawId`, and one of 1024 bytes (1023 taken); a key of alg `-257` with kty `2`, of alg `-7` with kty `3`, of crv `2`, with a sixth member, and off the curve; an RS256 key of 2048 and of 4096 bits, taken, and one with `n` of 255 bytes, of 513, and with a first byte of zero, and with `e` even, and `1`; extensions with ED clear, and none with ED set; a byte after the key; a credential ID another account has. `passkey-register` with the authorization page's `Referer`, and `sign-in` with the passkey page's, `400 invalid_request`. - **Signing in.** The authorization page's `__passkeyOptions`: its options as above, a new challenge each load, which `passkey-sign-in` from that device takes, and which a later load or `passkey-options` replaces. `passkey-options`: its options as above, a new challenge each call, and with no device cookies `400 invalid_request`. `passkey-sign-in` with `remember: true`: `{account}`, the page's `__sessions` then listing it, `_passkeyList` its `lastUsedAt` within a second, `_oauthDevices` the device; with `remember: false`, an `ephemeralToken` that `consent` takes, and the account not listed; both through to a code and a token, for each issuer. With the email factor on, signed in with no code, and nothing mailed. Refused, each with one thing wrong and no sign-in: no challenge; a challenge already spent, by a sign-in and by a failure; the challenge of another device; the credential's form; no `userHandle`, and another account's; a credential ID of no passkey, and of one removed; `type` `webauthn.create`; another challenge; another origin; `crossOrigin: true`; a `topOrigin`; another `rpIdHash`; UP clear; UV clear; BE other than the passkey's; AT set; a signature by another key, over other bytes, and not DER; with an RS256 passkey, which signs in, a signature by another key and one a byte short; a count not greater than the last, and a count of zero after one that was not; a taken-down account. A signature with `s` in the upper half, taken; a count of zero, twice, taken; a deactivated account, signed in, its consent `access_denied`. - **Removing.** `_passkeyRemove` of one: its sign-in refused, the account's other passkey still signing in; another account's `id`, and an `id` no passkey has, `200 {}`, removing nothing. - **States.** A password reset: every passkey of the account gone, and its link ended. A takedown: sign-in refused, then taken again once lifted. With `--lifecycle`, after each change of an account's state, its password token on the three routes, as the rows of `LIFECYCLE.md`'s "Its own calls" give them, and a deleted account's passkey no longer signing in. - **Free space.** With `--limits`, below `PDS_MIN_FREE_BYTES`: `passkey-register` and `passkey-sign-in` `507`, adding and signing in nothing; `_passkeyAdd` and `_passkeyRemove` answered. - **Commands.** The tools and commands as `COMMANDS.md` checks them. - **Crashes.** With `--crash-every`, a passkey added, one removed, and a sign-in made before a kill: after the restart, the first listed and signing in, the second neither, and the sign-in's count kept, so that an assertion with that count is refused; a link made before, its page the error page; a challenge made before, `passkey-sign-in` refused. - **Pages.** With `--pages`, `OAUTH-PAGES.md`'s passkey flows, in Chromium with its virtual authenticator, on a server whose `PDS_PUBLIC_URL` is `http://localhost:`, a host a browser takes as an RP ID.