Passkeys
An account may sign in on the authorization page (OAuth: the authorization server) 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: the account's own sessions and devices’s are; their MCP tools and CLI commands are in
Commands: every method as an MCP tool and a CLI command, “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: what the authorization pages show.
Sources
Section titled “Sources”This section is informative.
| File | Description | 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
Section titled “The relying party”-
RP ID. The host of the issuer (OAuth: the authorization server, “The issuer”), without its port:
pds.example.comforhttps://pds.example.com,localhostforhttp://localhost:2583.Note: a browser takes no IP address as an RP ID, so with an issuer of
http://127.0.0.1:<port>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: oncePDS_PUBLIC_URLnames 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.
_passkeyList, _passkeyAdd and _passkeyRemove take the token
OAuth: the account's own sessions and devices’s routes take, and refuse the others as they do
(OAuth: the account's own sessions and devices, “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
Section titled “Requests”Past the auth, each route checks, in this order:
- Its HTTP method:
400 InvalidRequest. - For
_passkeyAdd, the account’s state: taken down is401 AccountTakedown, and deleted403 AccountNotFound(Account lifecycle, “Its own calls”). - For
_passkeyAddand_passkeyRemove, the body: one longer than 153600 bytes is413 PayloadTooLargeError, as for any method with a JSON input (Limits, “Request size”); thenContent-Type: application/json, and a JSON object with, for_passkeyAdd,namea string of 1 to 64 characters (Unicode code points), and for_passkeyRemove,ida string; else400 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), and has its route, as _passkeyList, in
its request line, its metrics and its span, as any request
(Operations). None is refused below PDS_MIN_FREE_BYTES: _passkeyAdd
keeps nothing on disk, and _passkeyRemove keeps the end of something, as
OAuth: the account's own sessions and devices’s revocations do.
_passkeyList
Section titled “_passkeyList”{"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:
idis its credential ID.nameis the name_passkeyAddwas given for it.createdAtis whenpasskey-registeradded it, andlastUsedAtits last sign-in bypasskey-sign-in, left out when it has none; each a datetime as atproto's Lexicon spec defines it, in UTC, with milliseconds.backedUpis the backup state (BS) its authenticator data last gave (webauthn/webauthn-3.md, §6.1.3).
_passkeyAdd
Section titled “_passkeyAdd”{name} makes a link that adds a passkey of that name to the token’s
account, and answers:
{"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.
urlis<issuer>/oauth/passkey?token=<token>, where<token>is 32 random bytes, base64url: the link. It is a secret: whoever opens it in time adds a passkey to the account.expiresAtis 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
Section titled “_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: the account's own sessions and devices’s routes end those.
The passkey page
Section titled “The passkey page”GET /oauth/passkey?token=<token> is a navigation, and is refused
otherwise, as the authorization page is (OAuth: the authorization server, “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: what the authorization pages show builds a page (“How the pages are built”), with one
statement, window["__passkeyData"]=JSON.parse("…");, of:
account:{did, handle}, andnameandpicturewhen the account has them, as OAuth: the authorization server gives an account’s (OAuth: the authorization server, “The authorization page”).name: the link’s name.expiresAt: when the link ends, as_passkeyAddanswered it.options: the registration’s options,PublicKeyCredentialCreationOptionsin the JSON formparseCreationOptionsFromJSON()takes (webauthn/webauthn-3.md, §5.1.8), byte strings in base64url:
| Member | Description |
|---|---|
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
Section titled “passkey-register”The passkey page’s script calls POST /@atproto/oauth-provider/~api/passkey-register with {credential}, checked
as OAuth: the authorization server 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"}:
- 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 isaccess_denied. Every check after this one fails withinvalid_request. - Its form:
credentialan object withidandrawIdthe same string, base64url;typepublic-key; andresponsean object withclientDataJSONandattestationObjectbase64url strings, andtransports, when present, an array of strings. Its other members are ignored. - The client data (§7.1, steps 5 to 11):
clientDataJSONUTF-8, a leading byte order mark dropped, a JSON object whosetypeiswebauthn.create, whosechallengeis the link’s, base64url, whoseoriginis the origin above, whosecrossOriginis absent orfalse, and which has notopOrigin. Its other members are ignored. - The attestation object (§7.1, steps 13 and 19 to 24):
attestationObjectone CBOR item (webauthn/rfc8949.txt), with nothing after it: a map of exactlyfmt,attStmtandauthData;fmtnone, andattStmtan empty map (§8.7);authDataa byte string. - The authenticator data (§6.1, §7.1, steps 14 to 18):
rpIdHashthe 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 bytesrawIdnames; andcredentialPublicKey, one CBOR item, a COSE_Key (webauthn/rfc9052.txt, §7) of one of the algorithms above: for ES256, a map of exactly1(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 exactly1(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. - 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
Section titled “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: the authorization server 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: the authorization server, “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):
{"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
Section titled “The page’s options”The authorization page, when it answers 200 (OAuth: the authorization server, “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: what the authorization pages show, “Sign in”). The page is not refused below
PDS_MIN_FREE_BYTES for it: a challenge is kept in memory alone.
passkey-options
Section titled “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
Section titled “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:
-
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.
-
Its form:
credentialan object withidandrawIdthe same string, base64url;typepublic-key; andresponsean object withclientDataJSON,authenticatorData,signatureanduserHandle, base64url strings. Its other members are ignored. -
The passkey (§7.2, step 6): a passkey of the credential ID
rawIdnames, whose account’s user handle isuserHandle. -
The client data (§7.2, steps 8 to 14): as
passkey-register’s, buttypewebauthn.get, andchallengethe device’s. -
The authenticator data (§7.2, steps 15 to 19): at least 37 bytes;
rpIdHashthe 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. -
The signature (§7.2, steps 20 and 21):
signature, by the passkey’s public key, overauthenticatorDatafollowed by the SHA-256 ofclientDataJSON: for ES256, an ECDSA signature, DER-encoded, ansin 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. -
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.
-
The account: one taken down is
400 invalid_request,Account was taken down, assign-inanswers it (Account lifecycle, “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: the authorization server, “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: the account's own sessions and devices); 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), passkey-sign-in signs in with no code, and mails
none. It costs no rate limit, as the API’s other calls (OAuth: the authorization server, “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 for MCP clients), which uses the same page.
The account’s states
Section titled “The account’s states”_passkeyList,_passkeyAddand_passkeyRemoveanswer in each of the account’s states as Account lifecycle’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, “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 (Account lifecycle, “deleteAccount”) removes every passkey of the account and ends its link.
Durability
Section titled “Durability”As Durability 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
Section titled “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;_passkeyAddand_passkeyRemovewith no body, a body that is not JSON, with nonameorid, anameof 0 and of 65 characters, and one of 64 characters of four bytes each, taken; one of 153601 bytes,413 PayloadTooLargeError. - Adding.
_passkeyAdd: itsurlandexpiresAt900 seconds on, within a second. The page:__passkeyDataas above, itsoptionsmember by member,user.idthe 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, andexcludeCredentialsthe account’s passkeys, compared as a set; at 20 passkeys,_passkeyAdd400 InvalidRequest; twopasskey-registers through one link at once, one200 {}and the otheraccess_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. Thenpasskey-registerwith the harness’s authenticator:200 {},_passkeyListlisting it with its name,createdAtwithin a second, nolastUsedAt, andbackedUp, 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;typewebauthn.get; another challenge; another origin, and the issuer’s with another port;crossOrigin: true; atopOrigin; a byte order mark, taken; anotherrpIdHash; UP clear; UV clear; BS without BE; AT clear;fmtpacked; a non-emptyattStmt; an attestation object with a fourth key, and with a byte after it; a credential ID other thanrawId, and one of 1024 bytes (1023 taken); a key of alg-257with kty2, of alg-7with kty3, of crv2, with a sixth member, and off the curve; an RS256 key of 2048 and of 4096 bits, taken, and one withnof 255 bytes, of 513, and with a first byte of zero, and witheeven, and1; extensions with ED clear, and none with ED set; a byte after the key; a credential ID another account has.passkey-registerwith the authorization page’sReferer, andsign-inwith the passkey page’s,400 invalid_request. - Signing in. The authorization page’s
__passkeyOptions: its options as above, a new challenge each load, whichpasskey-sign-infrom that device takes, and which a later load orpasskey-optionsreplaces.passkey-options: its options as above, a new challenge each call, and with no device cookies400 invalid_request.passkey-sign-inwithremember: true:{account}, the page’s__sessionsthen listing it,_passkeyListitslastUsedAtwithin a second,_oauthDevicesthe device; withremember: false, anephemeralTokenthatconsenttakes, 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; nouserHandle, and another account’s; a credential ID of no passkey, and of one removed;typewebauthn.create; another challenge; another origin;crossOrigin: true; atopOrigin; anotherrpIdHash; 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 withsin the upper half, taken; a count of zero, twice, taken; a deactivated account, signed in, its consentaccess_denied. - Removing.
_passkeyRemoveof one: its sign-in refused, the account’s other passkey still signing in; another account’sid, and anidno 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 Account lifecycle’s “Its own calls” give them, and a deleted account’s passkey no longer signing in. - Free space. With
--limits, belowPDS_MIN_FREE_BYTES:passkey-registerandpasskey-sign-in507, adding and signing in nothing;_passkeyAddand_passkeyRemoveanswered. - Commands. The tools and commands as Commands: every method as an MCP tool and a CLI command 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-inrefused. - Pages. With
--pages, OAuth: what the authorization pages show’s passkey flows, in Chromium with its virtual authenticator, on a server whosePDS_PUBLIC_URLishttp://localhost:<port>, a host a browser takes as an RP ID.