Appearance
Passkey sign-in
A passkey lets users sign in with their fingerprint, face or screen lock instead of typing an email and password. It needs no outside account and costs nothing. The website needs only your domain on https. The mobile app also needs your domain linked to the app, which takes about 20 minutes.
You need
- The site live on its own domain over
https(APP_URL=https://yourdomain.com). Browsers never allow passkeys on an IP address or on plainhttp(onlylocalhostis an exception, for testing). - For the Android app: access to Google Play Console (or the keystore you sign the app with).
- For the iOS app: an Apple Developer account and the Xcode project (
mobile/ios).
How passkeys work here
A passkey is a key pair made by the user's phone, computer or password manager (iCloud Keychain, Google Password Manager, 1Password, Windows Hello, a security key such as a YubiKey). The private key never leaves the device. The exchange stores only the public key (table passkeys).
- When the user signs in, the server sends a one-time challenge. The device asks for the fingerprint, face or PIN, signs the challenge, and the server checks the signature.
- Every passkey is tied to one domain, the relying party ID (
PASSKEYS_RP_ID). The device only offers it on that domain or in an app linked to it. A fake site on another address gets nothing, so passkeys can't be phished. - Passkeys are discoverable: the user doesn't type an email. The device shows the accounts it has for your site and the user picks one.
- User verification is required: tapping a security key without a PIN is not enough. That is why a passkey sign-in counts as both factors and no 2FA code is asked.
The same server code (App\Services\Auth\PasskeyService) serves the website and the app. The crypto checks (signature, origin, domain, user verification, signature counter) come from the laravel/passkeys and web-auth/webauthn-lib packages, which are already installed.
Turn passkeys on for the website
Make sure
APP_URLis your final https address, for examplehttps://yourdomain.com.Set the passkey values in
.env:iniPASSKEYS_ENABLED=true PASSKEYS_RP_ID=yourdomain.com PASSKEYS_ORIGINS=Clear the config cache:
bashphp artisan config:clear
That's all for the website. The Sign in with a passkey button appears on /login, and Passkeys appears in the account menu.
Choosing the values
| Key | Default | What to put |
|---|---|---|
PASSKEYS_ENABLED | true | false hides passkeys everywhere (website and app). Saved passkeys stay in the database and work again when you turn it back on. |
PASSKEYS_RP_ID | the host of APP_URL | The domain passkeys belong to, without https:// and without a path, e.g. yourdomain.com. It must be the site's host or a parent domain of it. Never an IP address: with an IP, passkeys are switched off and the buttons are hidden. |
PASSKEYS_ORIGINS | none | Other addresses users open the site at, comma separated, with https://. APP_URL is always allowed and doesn't need to be listed. |
Examples
| Your setup | PASSKEYS_RP_ID | PASSKEYS_ORIGINS |
|---|---|---|
Site on https://yourdomain.com only | yourdomain.com (or leave empty) | empty |
Site on https://yourdomain.com and https://www.yourdomain.com | yourdomain.com | https://www.yourdomain.com |
Site on https://exchange.yourdomain.com, and you want passkeys to keep working if you move it to another subdomain later | yourdomain.com | https://yourdomain.com (needed by the iOS app, see below) |
Every address is checked exactly (scheme + host + port). A user who opens the site on an address that is not APP_URL and not in PASSKEYS_ORIGINS gets "We couldn't verify this passkey" (this is what stops phishing sites).
Pick the domain once
A passkey belongs to the PASSKEYS_RP_ID it was made with. If you change it (or move the exchange to another domain), every existing passkey stops working. Users then sign in with their password and add a new passkey. Their password always keeps working, so nobody is locked out, but choose the domain before launch.
Check it
- Open
https://yourdomain.com/loginin Chrome, Safari, Edge or Firefox. The Sign in with a passkey button is under the form. - No button? Either the server has passkeys off (
PASSKEYS_ENABLED=false, an IP inAPP_URL, orconfig:clearnot run) or the browser can't use them here (no https).
What users see on the website
Adding a passkey
- Account → Passkeys (
/user/profile/passkeys), or the Passkeys row in the account overview. - Add passkey → optional name (e.g. "Work laptop") → password, plus the 2FA code when 2FA is on (authenticator or SMS code; Send code by SMS under the field texts one).
- The browser shows its own passkey prompt: fingerprint, face, Windows Hello, the phone's screen lock, or "use a phone" (QR code) to save it on a phone.
- The passkey appears in the list with its name, the authenticator (e.g. "iCloud Keychain", "Google Password Manager" when the device reports it; otherwise the name the user typed), the date it was added and Last used.
Users can rename a passkey (pencil icon) and remove it (password + 2FA code). Up to 10 passkeys per account.
Signing in
/login→ Sign in with a passkey.- The browser lists the passkeys it has for your site (on this device, in the synced password manager, or on a nearby phone through the QR code).
- The user picks one and confirms with fingerprint, face or PIN.
- They are signed in and sent to the page they wanted, or the default home page. "Remember me" is on for passkey sign-ins.
If the user closes the browser prompt, nothing is shown (it is not an error). Other problems are shown under the button.
What users see in the app
- Sign in screen → Sign in with a passkey. The phone's own passkey sheet opens (Android Credential Manager, or the iOS passkey sheet), the user confirms with fingerprint, face or screen lock, and the app is signed in. The app sign-in is listed in Devices like any other.
- Account → Security → Passkeys (
/security/passkeys): the same list as the website, Add passkey (password + 2FA code, then the phone's sheet), rename and remove. - The button and the Security row only show when the server allows passkeys (
GET api/v1/auth/oauth/providers→"passkeys": true) and the phone supports them: Android 9 or newer with Google Play services, iOS 16 or newer.
Passkeys are shared across the website and the app: a passkey added in the app (saved to Google Password Manager or iCloud Keychain) also signs in on the website in a browser that uses the same password manager, and the other way round. That only works once the domain is linked to the app (next two sections).
Link your domain to the Android app
Android only lets an app use the passkeys of a domain that lists the app in https://<domain>/.well-known/assetlinks.json. The exchange serves that file for you from .env.
1. Find the package name
It is the applicationId in mobile/android/app/build.gradle.kts. In this project: exchange.cryptotech.exchange_app. If you renamed the app, use your new ID.
2. Find the SHA-256 signing fingerprint(s)
The fingerprint looks like AB:CD:12:… (32 pairs). You usually need two:
Google Play builds: Play Console → your app → Test and release → App integrity → App signing. Copy the SHA-256 certificate fingerprint of the App signing key certificate (what users install from Play) and of the Upload key certificate (what you install yourself for testing).
Builds you sign yourself (APK outside Play): read it from your keystore:
bashkeytool -list -v -keystore /path/to/upload-keystore.jks -alias uploadFor a debug build on a developer machine (testing only):
bashkeytool -list -v -keystore ~/.android/debug.keystore -alias androiddebugkey -storepass androidOr run
./gradlew signingReportinmobile/android.
3. Fill in .env
ini
PASSKEYS_ANDROID_PACKAGE=exchange.cryptotech.exchange_app
PASSKEYS_ANDROID_FINGERPRINTS=AB:CD:...:EF,12:34:...:56bash
php artisan config:clearThe fingerprints are used twice:
- they are published in
/.well-known/assetlinks.json(only values in the exactAA:BB:…32-pair format are published), and - they are turned into the origin Android signs with (
android:apk-key-hash:<base64url of the fingerprint>) and added to the allowed origins automatically. You don't add anything toPASSKEYS_ORIGINSfor Android.
4. Check the file
bash
curl -i https://yourdomain.com/.well-known/assetlinks.jsonIt must answer 200 with JSON like:
json
[{"relation":["delegate_permission/common.handle_all_urls","delegate_permission/common.get_login_creds"],
"target":{"namespace":"android_app","package_name":"exchange.cryptotech.exchange_app",
"sha256_cert_fingerprints":["AB:CD:...:EF","12:34:...:56"]}}]A 404 means PASSKEYS_ANDROID_PACKAGE is empty, no fingerprint is in the right format, or config:clear wasn't run. Google's Statement List Tester can check it too.
Web server
The file comes from Laravel, not from a file on disk. The nginx example in Installation already lets /.well-known/ through (location ~ /\.(?!well-known) { deny all; }). If you wrote your own rule that blocks every path starting with a dot, add the same exception. The file must be reachable over https without a redirect.
Link your domain to the iOS app
iOS only lets an app use a domain's passkeys when both sides agree: the domain lists the app in /.well-known/apple-app-site-association, and the app declares the domain in its Associated Domains.
1. Find the app ID
It is TEAMID.bundle.id:
- Team ID: developer.apple.com/account → Membership details → Team ID (10 letters/digits, e.g.
A1B2C3D4E5). - Bundle ID: Xcode → Runner target → General → Bundle Identifier. In this project:
exchange.cryptotech.exchangeApp.
2. Fill in .env
ini
PASSKEYS_IOS_APP_IDS=A1B2C3D4E5.exchange.cryptotech.exchangeAppbash
php artisan config:clearCheck it:
bash
curl -i https://yourdomain.com/.well-known/apple-app-site-associationIt must answer 200 with {"webcredentials":{"apps":["A1B2C3D4E5.exchange.cryptotech.exchangeApp"]}}. A 404 means the value is empty or not in the TEAMID.bundle.id format.
3. Add Associated Domains in Xcode
This is not in the project yet, because it needs your Apple team:
- Open
mobile/ios/Runner.xcworkspacein Xcode. - Select the Runner target → Signing & Capabilities → + Capability → Associated Domains.
- Add
webcredentials:yourdomain.com(yourPASSKEYS_RP_ID, nohttps://). - Build and install the app again.
Xcode turns on the Associated Domains capability for the App ID in your developer account when signing is automatic. With manual signing, enable it on the App ID at developer.apple.com and download a new provisioning profile.
Apple fetches the association file through its own CDN when the app is installed, so a change can take a while (hours) to reach phones. Reinstall the app after you change it.
iOS and the RP ID
iOS signs with the origin https://<PASSKEYS_RP_ID>. When PASSKEYS_RP_ID is the same host as APP_URL (the usual case) there is nothing to add. When it is a parent domain (site on exchange.yourdomain.com, RP ID yourdomain.com), add https://yourdomain.com to PASSKEYS_ORIGINS, and serve both .well-known files on https://yourdomain.com as well (proxy them from the exchange, or copy the JSON there). The same goes for Android's assetlinks.json.
Security rules
These are enforced on the server for the website and the app alike:
| Rule | Detail |
|---|---|
| Adding needs password + 2FA | The password and, when 2FA is on, a 2FA code (authenticator, SMS or recovery code). This returns a one-time ticket that is valid for 5 minutes, works once and only for that user. So someone who sits down at an unlocked, signed-in computer can't add their own passkey. |
| Removing needs password + 2FA | Same check. Renaming needs nothing extra (it only changes a label). |
| Notices | Adding sends an email ("Passkey added", or an SMS for accounts without an email) and a push to the user's phones. Removing sends an email. |
| Limit | 10 passkeys per account, checked under a lock so parallel requests can't pass it. The same authenticator can't be added twice. |
| Single-use challenges | Each sign-in challenge lives 5 minutes and is deleted the moment it is used, even when the check fails (no replay). On the website it is also bound to the browser session that asked for it; app challenges can't be used on the website and the other way round. |
| Checked by the library | The signature, the origin (APP_URL, PASSKEYS_ORIGINS, Android app hash), the RP ID, that user verification happened, and that the signature counter never goes backwards (a sign of a cloned key). |
| Blocked accounts | Deactivated and deleted accounts are refused after the check, with the same message as a password sign-in. |
| No 2FA code at sign-in | On purpose: user verification is required, so a passkey already means "the device" + "the fingerprint, face or PIN". Password sign-in still asks for 2FA. |
| Sign-in alerts | A passkey sign-in from a new device sends the usual sign-in alert. |
| API keys | API keys from API Management can't list, add, rename or remove passkeys (403). Only the website session and the app can. |
| Throttling | Website: 20 challenge requests and 10 sign-in attempts per minute. App: the same. Adding and removing: 10 per 10 minutes. |
| Closing an account | Deletes all its passkeys. |
| Errors never leak | Any malformed or forged answer is a normal "couldn't verify" message (422), never a server error. |
The password always keeps working. A user who loses their phone signs in with their password (and 2FA), then removes the lost passkey under Passkeys.
Support: when a user is stuck
| User says | What to tell them |
|---|---|
| "My phone shows no passkey for this site" | They haven't added one on this device or password manager yet. Sign in with the password, then Account → Passkeys → Add passkey. A passkey saved in iCloud Keychain doesn't show up in Google Password Manager and vice versa; on a computer they can use Use a phone / QR code. |
| "Passkey not recognized. It may have been removed from your account." | The passkey on the device was removed from the account (or made on a test or old domain). They should delete it from the device's password manager and add a new one. |
| "I lost my phone" | Sign in with the password, remove the old passkey under Passkeys, and change the password if the phone wasn't locked. |
| "I want to remove a passkey but have no 2FA codes" | The usual Lost authenticator steps first. |
For developers: endpoints
All endpoints answer JSON. Errors are 422 with the message under errors.credential (or errors.password / errors.twofa).
Website (session + CSRF, guests only):
| Route | Purpose |
|---|---|
POST /passkey/login/options | Challenge → {ticket, options} (options = WebAuthn request options, base64url strings) |
POST /passkey/login {ticket, credential, remember?} | Signs the browser in → {redirect} |
App (/api/v1, no token):
| Route | Purpose |
|---|---|
GET auth/oauth/providers | passkeys: true/false decides whether the app shows the button |
POST auth/passkey/options | {available: false} or {available: true, ticket, options} |
POST auth/passkey/token {ticket, credential, device_name} | {status: true, token} (a normal app token, listed in Devices) |
Account (/api/v1, signed-in website session or app token; API keys refused):
| Route | Purpose |
|---|---|
GET account/passkeys | {available, max, items: [{id, name, authenticator, created_at, last_used_at}]} |
POST account/passkeys/options {password, twofa?} | {ticket, options} (WebAuthn creation options) |
POST account/passkeys {ticket, credential, name?} | Saves it → {passkey} |
PATCH account/passkeys/{id} {name} | Rename (max 60 characters, HTML stripped) |
POST account/passkeys/{id}/delete {password, twofa?} | Remove |
credential is the standard WebAuthn JSON (id, rawId, type: "public-key", response with base64url fields), at most 64 KB. The website builds it in resources/js/Functions/Auth/passkey.js; the app uses the passkeys Flutter package (mobile/lib/features/security/data/passkey_repository.dart).
Test it
Website
- Sign in with email and password → Account → Passkeys → Add passkey → password (+ 2FA) → confirm with fingerprint / Windows Hello. The passkey is listed and a "Passkey added" email arrives.
- Sign out →
/login→ Sign in with a passkey → pick it → you are signed in with no 2FA code. Last used is updated. - Remove the passkey (password + 2FA), sign out, try Sign in with a passkey again → "Passkey not recognized" (or the device offers nothing).
No real device at hand? Chrome DevTools → ⋮ → More tools → WebAuthn → Enable virtual authenticator environment → add an authenticator with Supports resident keys and Supports user verification ticked. It behaves like a fingerprint reader.
App (after the Android/iOS linking above, with a release or Play-signed build whose fingerprint is in .env)
- Account → Security → Passkeys → Add passkey → password (+ 2FA) → phone sheet → saved.
- Sign out → Sign in with a passkey → phone sheet → signed in.
- On a computer whose browser uses the same Google / iCloud account, the same passkey signs in on the website.
Local testing
On a local machine with an IP address in APP_URL passkeys are off. To try them, open the site through a host name (e.g. http://ico.loc in /etc/hosts), set PASSKEYS_RP_ID=ico.loc and PASSKEYS_ORIGINS=http://ico.loc, and start Chrome with --unsafely-treat-insecure-origin-as-secure=http://ico.loc (or use localhost, which browsers treat as secure). Real phones need a public https domain with the .well-known files, so test the app on staging.
Common errors
| What you see | Cause and fix |
|---|---|
| No Sign in with a passkey button (website) | PASSKEYS_ENABLED=false, APP_URL / PASSKEYS_RP_ID is an IP address, config:clear not run, or the page is on plain http (the browser refuses). |
| No button (app) | Same server reasons (check GET /api/v1/auth/oauth/providers → "passkeys": true), or the phone is older than Android 9 / iOS 16 or has no Google Play services. |
| Passkeys need a secure (https) connection. | The page is on http, or PASSKEYS_RP_ID is not the site's host or a parent of it (browser SecurityError). |
| We couldn't verify this passkey. Please try again. | The address in the browser is not APP_URL or in PASSKEYS_ORIGINS (e.g. www. missing), the Android fingerprint of this build is not in PASSKEYS_ANDROID_FINGERPRINTS, or the passkey was made for another RP ID. Details are in storage/logs/laravel-*.log as "Passkey sign-in refused: …". |
| Unable to register passkey. Please try again. | Same origin/RP ID causes during adding. Log line "Passkey registration refused: …". |
| Sign-in expired. Please try again. / This request expired. Please try again. | More than 5 minutes passed, the challenge was already used, or the cache was cleared. On the website: the session changed between the two steps (e.g. cookies blocked). |
| Unable to register this passkey. | This passkey is already saved on an account (possibly another one). Remove it from that account first, or use another device. |
| This passkey is already added to your account. | This device already has a passkey for the account. Nothing to do. |
| You can add up to 10 passkeys. Remove one first. | Limit reached. |
| App: Passkeys can't be used on this device. | The domain is not linked to the app: assetlinks.json / apple-app-site-association returns 404 or lists another package / fingerprint / Team ID, or the iOS Associated Domains entry is missing. Fix, then reinstall the app. |
| App: No passkey for this account on this device. | The phone's password manager has no passkey for your domain. Add one first. |
| Passkeys are not available on this site. | The server has passkeys off (see the first row) but an old page or app still tried. Reload. |
Related pages
- Security & 2FA → Passkeys: the user-side summary.
- Environment variables → Sign-in providers and Mobile app for every
PASSKEYS_*key. - Build & publish the app → Server checklist.
