Skip to content
Dashboard
Theme
Theme

Passkeys

Passkey sign-in and enrolment on the hosted login, and passkeys as a second factor.

View Markdown

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 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 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. 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.

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 and Android SDKs explain how to plug in native passkey prompts.