# Passkeys

Users can sign in with a passkey (WebAuthn discoverable credentials) on the hosted login. A passkey also counts as a second factor.

- **Sign-in:** the hosted page offers passkeys when the environment enables the `passkey` method. The browser shows the user's passkeys for your login host.
- **Enrolment during sign-in:** a user without a second factor can add a passkey instead of an authenticator app when MFA is required; that sign-in then completes with MFA.
- **Account page:** users add and remove passkeys at the account page. A user who already has a factor adds another only after a sign-in in the last 10 minutes that passed a second factor ([`step_up_required`](/errors/step_up_required/) otherwise), the same as removing one.
- **Rename:** users rename a passkey on the account page (`POST /login/<environment>/api/factors/{factor}/rename`); your server uses `PATCH /v1/users/{user}/passkeys/{passkey}` with a `name` of 1 to 64 characters. Authenticator apps and other users' passkeys answer `resource_not_found`.
- **Your server:** `GET /v1/users/{user}/factors` lists a user's passkeys and authenticator apps; `DELETE /v1/users/{user}/factors/{factor}` removes one.

The relying party ID is the sign-in host (`signin.ohauthcat.com`), shared by every environment; each credential still belongs to one environment's user.

## Native apps

Native apps can use the hosted login in the system browser, or run the passkey ceremony themselves with the platform's passkey prompt. For the second, list the app in the environment's `native_app_origins` in `PUT /v1/user_management/settings`:

- Android: `android:apk-key-hash:<hash>`, the origin Android sends for your signed app;
- iOS: `ios:<team ID>.<bundle ID>`. iOS apps send the sign-in origin, so the sign-in host must list the app in its web credentials association.

An origin in any other form answers [`native_origin_invalid`](/errors/native_origin_invalid/). Your server then calls the headless routes with its secret key:

- `POST /v1/users/{user}/passkeys/registration_options` and `POST /v1/users/{user}/passkeys` to add a passkey;
- `POST /v1/user_management/passkeys/authentication_options` and `POST /v1/user_management/passkeys/authenticate` to verify one.

Options expire after 5 minutes. A headless authentication confirms the user. To also start a session, send `session: true` with `client_id` (a live publishable key of the environment): the answer then carries `access_token`, `refresh_token`, `id_token`, `token_type`, `expires_in` and `session_id`, issued by the login host for that client. When MFA is required and the passkey was not user-verified, it answers [`mfa_required`](/errors/mfa_required/).

### App-link files

The sign-in host serves `/.well-known/apple-app-site-association` (`webcredentials` for every `ios:` origin in `native_app_origins`) and `/.well-known/assetlinks.json` (`get_login_creds` for every entry of `android_apps`). Set `android_apps` in `PUT /v1/user_management/settings` as a list of `{package_name, apk_key_hash}`; each hash must also be listed in `native_app_origins` as `android:apk-key-hash:<hash>`. Changes reach the files within about five minutes. The [iOS](/sdks/ios/) and [Android](/sdks/android/) SDKs explain how to plug in native passkey prompts.
