Skip to main content

Documentation Index

Fetch the complete documentation index at: https://auth0.com/llms.txt

Use this file to discover all available pages before exploring further.

Passkeys are a phishing-resistant alternative to traditional forms of authentication (such as username and password) that offer an easier and more secure user experience. They are modeled from FIDO® W3C Web Authentication (WebAuthn) and Client to Authenticator Protocol (CTAP) specifications. Auth0 currently supports passkeys as an authentication method for database connections with two methods of implementation:

Before you start

Configure a custom domainNative passkeys require the use of a . Before proceeding, ensure you have configured a custom domain for your tenant. To learn more, review Custom Domains.Configure your passkey policyBefore you can implement native passkeys for Android or iOS applications, you must configure a passkey policy in your Auth0 tenant. To prepare your tenant, follow the steps in Configure Passkey Policy.Prepare your applicationAll applications using the Passkey APIs must add the Passkey grant and configure the Relying Party ID (RP ID). Depending on your platform, you may also need to configure additional settings through your or the .

​
How it works

The Passkey APIs use a combination of the Auth0 Authentication API and platform-specific credential APIs to embed challenge flows directly into your application. For native mobile apps, this means using iOS or Android platform APIs. For web applications, this means using the WebAuthn browser API. This allows you to create an integrated signup and login experience that does not rely on redirecting users through their browsers to complete authentication. The following example demonstrates what a new user may experience during the passkey signup flow:
  1. A new user launches your mobile application and accesses the login screen. Since they are a new user, they select the Sign Up button.
  2. On the next screen, the user enters their email address and selects Create Account.
  3. Next, the user is asked if they want to create a passkey for your application. To proceed, the user selects Continue.
  4. To generate a passkey, the user must locally authenticate on their device using biometrics or another authentication method, such as entering a PIN.
  5. After local authentication is complete, a new passkey is saved to the user’s device and synced with their passkey provider, such as iCloud Keychain or Google Password Manager.
  6. After the passkey is saved, the user continues your new user registration process to finalize their account.
Once this process is complete, the user can authenticate with their saved passkey the next time they log in to your application.

​
Configure device settings

Configure Device Settings in Auth0 Dashboard:
  1. Navigate to Applications > Applications and select your application.
  2. At the bottom of the Settings tab, select Advanced Settings.
  3. Choose the Device Settings tab.
  4. In the iOS section, enter your IDs from Apple:
    • Team ID
    • App ID
  5. Select Save Changes.
  • Auth0 automatically hosts the apple-app-site-association file on your tenant’s custom domain at https://YOUR_CUSTOM_DOMAIN/.well-known/apple-app-site-association based on the Team ID and App ID you configure. You do not need to host this file yourself.
  • In Xcode, enable the Associated Domains entitlement and add an entry for your custom domain in a similar format: webcredentials:YOUR_CUSTOM_DOMAIN.

​
Enable the Passkey grant

To enable the Passkey grant on all platforms:
  1. Navigate to Applications > Applications and select your application.
  2. In the Advanced Settings section, select the Grant Types tab.
  3. Enable the Passkey grant, then select Save Changes.
Alternatively, use the Management API: Call the Update a Client endpoint and:
  • Update grant_types to include urn:okta:params:oauth:grant-type:webauthn.
  • For native apps, use the mobile object to specify iOS and Android device settings as needed.

​
Relying party ID (rpId)

For end users to authenticate with a single passkey across different application types or application types with different subdomains, set the relying party ID to the root or parent domain in Auth0 Dashboard > Tenant Settings.

​
Implement passkey flows

You can define the following passkey flows for your application:
  • Signup flow: Allows new users to generate and save a passkey during the user registration process.
  • Login flow: Allows an existing user who has already enrolled in passkeys to authenticate with their saved passkey during the login process.
  • Enrollment flow: Allows existing users to add a passkey to their account after authentication.

​
Signup flow

A user initiates the passkey signup flow on their first login attempt to your application. If the user provides an identifier that already exists, we recommend prompting the user to complete the login flow instead. Otherwise, the action will fail.
Native Passkey registration is not supported during signup when SMS/Email OTP verification is required on the same connection.
  1. Your application initiates the signup challenge by calling the POST /passkey/register endpoint:
POST /passkey/register
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "user_profile": {
    "email": "user@example.com",
    "name": "John Doe"
  }
},
  • If you do not specify a realm, your tenant’s default directory is used.
  • By default, email is the required identifier. If you have enabled Flexible Identifiers for your database connection, you may use a combination of email, phone_number, or username instead.
  1. Auth0 returns PublicKeyCredentialCreationOptions needed to create passkeys, along with an auth_session ID:
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rp": {
      "id": "YOUR_CUSTOM_DOMAIN",
      "name": "YOUR_CUSTOM_DOMAIN"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -8 },
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "GENERATED_ID",
      "name": "USER_EMAIL",
      "displayName": "USER_EMAIL_OR_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}
  1. Your application creates a passkey on the user’s device with the returned PublicKeyCredentialCreationOptions. The method depends on your platform:
Use ASAuthorizationPlatformPublicKeyCredentialProvider to create the credential with Face ID, Touch ID, or device PIN. To learn more, review iOS registration documentation.
  1. Your application uses the credential information from the registration process to call the POST /oauth/token endpoint to exchange credentials for tokens:
POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "scope": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}
  1. Auth0 creates a new user account and returns the requested tokens as shown in the example return:
{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}
To learn more about about calls and parameters for the signup flow, review the Authentication API explorer.

​
Login flow

An existing user initiates the passkey login flow when they attempt to log in to your application. This flow only applies to existing users who have saved passkeys to their accounts during initial signup.
  1. Your application calls the POST /passkey/challenge endpoint to initiate the login challenge:
POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION"
}
If you do not specify a realm, your tenant’s default directory is used.
  1. Auth0 returns PublicKeyCredentialRequestOptions along with an auth_session:
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION",
    "timeout": 60000,
    "rpId": "YOUR_CUSTOM_DOMAIN",
    "userVerification": "preferred"
  },
  "auth_session": "SESSION_ID"
}
  1. Your application uses the returned PublicKeyCredentialRequestOptions to retrieve a passkey from the user’s device. The method depends on your platform:
Use ASAuthorizationPlatformPublicKeyCredentialProvider to retrieve the credential with Face ID, Touch ID, or device PIN. To learn more, review iOS login documentation.
  1. Your application uses the credential information from the login process to call the POST /oauth/token endpoint to exchange credentials for tokens:
POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "YOUR_CLIENT_ID",
  "realm": "OPTIONAL_CONNECTION",
  "scope": "openid profile email",
  "audience": "YOUR_API_IDENTIFIER",
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "authenticatorData": "BASE64URL_AUTHENTICATORDATA",
      "clientDataJSON": "BASE64URL_CLIENTDATAJSON",
      "signature": "BASE64URL_SIGNATURE",
      "userHandle": "BASE64URL_USERHANDLE"
    },
    "clientExtensionResults": {}
  }
}
  1. Auth0 authenticates the credentials and returns the requested tokens:
{
  "access_token": "eyJz93a...TJVA95w",
  "refresh_token": "GEz...NaYM",
  "id_token": "eyJ0exA...f1jrv3",
  "token_type": "Bearer",
  "expires_in": 86400
}
To learn more about about calls and parameters for the login flow, review the Authentication API explorer.

​
Enrollment flow

The enrollment flow allows users to add a passkey to their account after they’ve already authenticated with another method, such as username and password. When an existing, authenticated user wants to enroll a new passkey, use the My Account API.

Before you start

Before initiating the enrollment flow, ensure you:
  1. Activate the My Account API for your tenant.
  2. Retrieve an access token with the create:me:authentication_methods scope for the /me endpoint.
For complete setup instructions, read My Account API.
  1. Your authenticated application calls the POST /me/v1/authentication-methods endpoint with the access token:
POST /me/v1/authentication-methods
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "type": "passkey",
  "connection": "CONNECTION_NAME"
}
  1. Auth0 returns a challenge and session ID:
{
  "authn_params_public_key": {
    "challenge": "GENERATED_CHALLENGE",
    "timeout": 60000,
    "rp": {
      "id": "YOUR_CUSTOM_DOMAIN",
      "name": "YOUR_CUSTOM_DOMAIN"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -8 },
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "authenticatorSelection": {
      "residentKey": "required",
      "userVerification": "preferred"
    },
    "user": {
      "id": "GENERATED_ID",
      "name": "USER_IDENTIFIER",
      "displayName": "USER_DISPLAY_NAME"
    }
  },
  "auth_session": "SESSION_ID"
}
  1. Your application uses the returned PublicKeyCredentialCreationOptions to create a passkey on the user’s device, following the same platform-specific steps as the signup flow:
Use ASAuthorizationPlatformPublicKeyCredentialProvider to create the credential with Face ID, Touch ID, or device PIN. To learn more, review iOS registration documentation.
  1. After the user creates the passkey with their authenticator, call the POST /me/v1/authentication-methods/passkey|new/verify endpoint to complete the enrollment:
POST /me/v1/authentication-methods/passkey|new/verify
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "auth_session": "SESSION_ID_FROM_STEP_1",
  "authn_response": {
    "id": "BASE64URL_ID",
    "rawId": "BASE64URL_RAWID",
    "type": "public-key",
    "authenticatorAttachment": "platform",
    "response": {
      "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON",
      "attestationObject": "BASE64URL_ATTESTATION_OBJECT"
    }
  }
}
Once this step completes successfully, the passkey is enrolled for the user and can be used for future authentications. To learn more about about calls and parameters for the enrollment flow, review the My Account API explorer.

​
Relying party ID

A passkey created in one of your applications can be used to sign in to your other applications, Native or Web Applications, when those applications share the same relying party ID (rpId). This works because passkey providers (iCloud Keychain, Google Password Manager, 1Password, Dashlane, and others) sync credentials across the user’s devices within the same provider.

​
Move users between platforms

In most cases, users do not need to scan a QR code or use a second device. The flow depends on whether the passkey is already available on the device they’re using:
  • Same provider, different device (most common): A user enrolls a passkey on your iOS app; their iCloud Keychain syncs it to their Mac, where they can sign in to your web app immediately. Same applies to Android passkeys synced via Google Password Manager to Chrome on a Chromebook or Windows PC signed into the same Google account.
  • Cross-ecosystem or shared device (less common): If the passkey isn’t available on the device the user is on (for example, an iPhone passkey used on a Windows PC, or a public computer), the browser offers a QR code to authenticate via the user’s phone using hybrid transport (CTAP 2.2). The user keeps their passkey on their phone; the QR code only bridges the two devices for that one sign-in.

​
Choose your Relying Party ID

The rpId determines which origins can use a passkey. Auth0 sets the rpId to your custom domain by default. Choose the rpId that best matches the scope across which you want passkeys to work — and no broader. Recommended: Use a parent domain that scopes to your authentication and product surfaces, such as auth.example.com or accounts.example.com. A passkey created with “rpId=auth.example.com works on auth.example.com and any subdomain of it (for example, app.auth.example.com, m.auth.example.com). Avoid using your eTLD+1 (registrable apex) as the rpId — for example, example.com. Setting the rpId at this level lets every subdomain of example.com request and use those passkeys, including marketing sites, third-party-hosted services, or domains operated by other teams. This expands the trust boundary far beyond your authentication surface. For more information on relying party ID, read:

​
Multi-domain and brand scenarios

If you serve multiple brand domains (e.g., login.brand1.com and login.brand2.com), passkeys do not automatically work across them — each domain has its own rpId. See Passkeys with Multiple Custom Domains for guidance on per-domain enrollment, communication, and migration patterns.

​
Configuration checklist

Once you’ve chosen an rpId, ensure all your applications share it:
  1. Use one custom domain as the rpId across every native and web application that should share passkeys.
  2. For Native Applications, configure Device Settings in the Auth0 Dashboard with your iOS Team ID/App ID and Android package name/SHA-256 fingerprint. Auth0 hosts the apple-app-site-association and assetlinks.json files on your custom domain automatically.
  3. For Web Applications, serve your web origin from the rpId or a subdomain of it, and add it to Allowed Web Origins for CORS.

​
Learn more

The following resources can be referenced when implementing passkey authentication for your application: