> ## Documentation Index > Fetch the complete documentation index at: https://docs-dev-actions-triggers-prototype.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. > Auth0 Authentication API specs for Native Passkeys # Native Passkeys API export const ReleaseStageNotice = ({feature, stage, plans, contact, terms}) => { const stageTextMap = { "beta": "Beta", "ea": "Early Access" }; const stageText = stageTextMap[stage] || "a product release stage"; const prsLink = "/docs/troubleshoot/product-lifecycle/product-release-stages"; const linkify = (text, url) => { return {text}; }; const includeDetails = (plans, contact, terms) => { const hasDetails = terms || plans || contact; if (!hasDetails) return null; return {plans && <>This feature is available for {linkify(`${plans} plans`, "https://auth0.com/pricing")}. } {contact && "To participate, contact " + contact + ". "} {terms && <>By using this feature, you agree to the applicable Free Trial terms in Okta's {linkify("Master Subscription Agreement", "https://www.okta.com/legal")}.} ; }; return The {feature} feature is in {linkify(stageText, prsLink)}. {includeDetails(plans, contact, terms)} ; }; 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. For complete implementation details, review [Native Passkeys for Mobile Applications](/docs/authenticate/database-connections/passkeys/native-passkeys-for-mobile-applications). Native passkeys use a combination of Auth0 and native iOS or Android APIs to embed challenge flows directly into your mobile application. The endpoints listed below are a subset of the Auth0 Authentication API. To learn more about using this API, review the [Authentication API Introduction](https://auth0.com/docs/api/authentication#introduction). Passkeys have three related flows: * **Signup**: Creates a new user account with a passkey as the primary authentication method. * **Enrollment**: Adds a passkey as an authentication method to an existing user's account. * **Login**: Challenges an existing user to authenticate using a passkey associated with their account. ## Signup Flow ### Request Signup Challenge `POST /passkey/register` Initiates the passkey signup flow for a new user. In response, Auth0 returns [PublicKeyCredentialCreationOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialcreationoptions) and a session ID. Check `timeout` under `authn_params_public_key` in response for session timeout. The passkey signup flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value. After the user registers a passkey, Auth0 enrolls them in the provided Organization. #### Request Parameters | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | **Required**. The `client_id` of your application. | | `realm` | **Optional**. The name of the connection to associate with this user.

If a connection is not specified, your tenant's default directory is used. | | `user_profile` | **Required**. An object containing identification information for the user. By default, this includes a valid `email` and an optional display `name`.

If you have enabled [Flexible Identifiers](/docs/authenticate/database-connections/activate-and-configure-attributes-for-flexible-identifiers) for your database connection, you may use a combination of `email`, `phone_number`, or `username` as identifiers. These options can be required or optional and must match your Flexible Identifier configuration.

If the passed identifier (such as `email`) already exists in the directory, the user should be prompted to complete the Login flow instead. | #### Code Samples ##### Request ```text lines theme={null} POST /passkey/register Content-Type: application/json { "client_id": "{YOUR_CLIENT_ID}", "realm": "{OPTIONAL_CONNECTION}", "user_profile": { "email": "{VALID_EMAIL_ADDRESS}", "name": "{OPTIONAL_USER_DISPLAY_NAME}", } } ``` ##### Response ```json lines expandable theme={null} HTTP/1.1 200 OK Content-Type: application/json { "authn_params_public_key": { "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", "timeout": {MILLISECONDS}, "rp": { "id": "{THE_CUSTOM_DOMAIN}", "name": "{THE_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-ENTERED_IDENTIFIER}", "displayName": "{USER-ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING}" } }, "auth_session": "{SESSION_ID}" } ``` #### Remarks * After the challenge request is complete, your application can continue the user registration process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs. * You must then [authenticate the new user](#authenticate-new-user) using information retrieved through the native APIs to complete the flow. ### Authenticate New User Native Passkey registration is not currently supported when SMS/Email OTP verification is required on the same connection during signup. `POST /oauth/token` Uses the Token endpoint to authenticate the user with the provided credentials to create their account and return the requested tokens. The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs: * [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys) * [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) #### Request Parameters | Parameter | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | **Required**. Include the value: `urn:okta:params:oauth:grant-type:webauthn` | | `client_id` | **Required**. The `client_id` of your application | | `realm` | **Optional**. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used. | | `scope` | **Optional**. Use `openid` to get an ID token or `openid profile email` to include user profile information in the ID token. | | `audience` | **Optional**. API identifier of the API for which you want to get an access token. | | `auth_session` | **Required**. Session ID returned during the initial passkey challenge request. | | `authn_response` | **Required**. An object containing the following items: | | `authn_response.id` | **Required**. Base64URL credential ID. | | `authn_response.rawId` | **Required**. Base64URL credential ID. | | `authn_response.type` | **Required**. Include the value: `public-key` | | `authn_response.authenticatorAttachment` | **Required**. Include the values: | | `authn_response.response` | **Required**. An object containing the following items: | #### Code Samples ##### Request ```text lines theme={null} 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": "{OPTIONAL_REQUESTED_SCOPE}", "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", "authn_response": { "id": "{BASE64URL_ID}", "rawId": "{BASE64URL_RAWID}", "type": "public-key", "authenticatorAttachment": "platform|cross-platform", "response": { "clientDataJSON": "{BASE64URL_CLIENT_DATA_JSON}", "attestationObject": "{BASE64URL_ATTESTATION_OBJECT}", {OTHER_PROPERTIES} }, } } ``` ##### Response ```json lines theme={null} HTTP/1.1 200 OK Content-Type: application/json { "access_token": "{BASE64_TOKEN}", "refresh_token": "{BASE64_TOKEN}", "id_token": "{BASE64_TOKEN}", "token_type": "Bearer", "expires_in": {SECONDS} } ``` ## Enrollment Flow Enrolling a new passkey for a user involves a two-step process using the My Account API. This flow ensures that the passkey enrollment is initiated securely and then verified. Before initiating the enrollment flow, ensure you have an access token with the `create:me:authentication_methods` scope for the `/me` endpoint. ### Initiate Passkey Enrollment `POST /me/v1/authentication-methods` The first step is to initiate the enrollment process. This is done by making a POST request to the `/me/v1/authentication-methods` endpoint. #### Request Parameters | Parameter | Description | | ------------ | ------------------------------------------------------------------------ | | `type` | **Required**. Include the value: `public-key`. | | `connection` | **Optional**. The name of the connection in which to create the passkey. | | `identity` | **Optional**. The user's identity. Used with linked accounts. | #### Code Samples ##### Request ```json lines theme={null} { "type": "passkey", "connection": "CONNECTION_NAME", "identity": "IDENTITY_USER_ID" } ``` ##### Response ```json lines theme={null} { "authn_params_public_key": { "challenge": "GENERATED_CHALLENGE_FOR_THIS_SESSION", "timeout": MILLISECONDS, "rp": { "id": "CUSTOM_DOMAIN", "name": "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_ENTERED_IDENTIFIER", "displayName": "USER_ENTERED_DISPLAY_NAME_OR_IDENTIFIER_IF_MISSING" } }, "auth_session": "SESSION_ID" } ``` #### Remarks * The `auth_session` property in the response body is the identifier of the current authentication session. This must be passed to the `/verify` endpoint. * After the challenge request is complete, your application can continue the user enrollment process using native [Android](https://developer.android.com/identity/passkeys/create-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) APIs. This will prompt the user to create a passkey with their authenticator (such as fingerprint scanner, security key, or phone). ### Verify Passkey Enrollment `POST /me/v1/authentication-methods/passkey|new/verify` The ID in the path is always `passkey|new` for new enrollments. Once the user has successfully created the passkey with their authenticator, the client application will receive an `AuthenticatorAttestationResponse` from the WebAuthn API. This response needs to be sent back to the Auth0 service to complete and verify the enrollment. * [Android registration documentation](https://developer.android.com/identity/passkeys/create-passkeys) * [iOS registration documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Register-a-new-account-on-a-service) #### Request Parameters | Parameters | Description | | ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth_session` | **Required**. The session identifier received in the response of the first POST request to `/me/v1/authentication-methods`. | | `authn_response` | **Required**. The `authn_response` parameter is based on the Web Authentication API specification. In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs. | | `authn_response.id` | **Required**. Base64URL credential ID. | | `authn_response.rawId` | **Required**. Base64URL credential ID. | | `authn_response.type` | **Required**. Include the value: `public-key`. | | `authn_response.authenticatorAttachment` | **Required**. Include the values: `platform`, `cross-platform`. | | `authn_response.response` | **Required**. An object containing the following items: | #### Code Samples ##### Request ```json lines theme={null} { "auth_session": "SESSION_ID", "authn_response": { "id": "BASE64URL_ID", "rawId": "BASE64URL_RAWID", "type": "public-key", "authenticatorAttachment": "platform|cross-platform", "response": { "clientDataJSON": "BASE64URL_CLIENT_DATA_JSON", "attestationObject": "BASE64URL_ATTESTATION_OBJECT" } } } ``` #### Remarks Once this step is completed successfully, the passkey is enrolled for the user and can be used for future authentications. ## Login Flow ### Request Login Challenge `POST /passkey/challenge` Initiates the passkey login flow for an existing user who saved a passkey to their account during their initial signup. In response, Auth0 returns [PublicKeyCredentialRequestOptions](https://www.w3.org/TR/webauthn-3/#dictdef-publickeycredentialrequestoptions), a session ID, and a Relying Party identifier `rpId`. Check `timeout` under `authn_params_public_key` in response for session timeout. The `rpId` returned in the response is the identifier the native device (iOS/Android) uses to look up saved credentials bound to a domain. For a passkey created on a web application (e.g., `example.com`) to be available in the native flow, the `rpId` returned must match the web's `rpId`. To learn how to customize the RP ID for your tenant, read [Configure Passkey Policy](/docs/authenticate/database-connections/passkeys/configure-passkey-policy#configure-relying-party-id-rp-id). The passkey login flow supports Organizations through the `organization` parameter, following the behavior described in [Login Flows for Organizations](/docs/manage-users/organizations/login-flows-for-organizations). If your application is configured for **Business Users**, you must provide the `organization` parameter and a valid Organization name or identifier value. All issued tokens are in the context of the provided Organization. If you enabled [Auto-Membership](/docs/manage-users/organizations/login-flows-for-organizations#auto-membership) for your Organization, the user is automatically enrolled in the Organization after successfully authenticating. #### Request Parameters | Parameter | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `client_id` | **Required**. The `client_id` of your application. | | `realm` | **Optional**. The name of the connection to associate with the user.

If a connection is not specified, your tenant's default directory is used. | #### Code Samples ##### Request ```text lines theme={null} POST /passkey/challenge Content-Type: application/json { "client_id": "{YOUR_CLIENT_ID}", "realm": "{OPTIONAL_CONNECTION}" } ``` ##### Response ```json lines theme={null} HTTP/1.1 200 OK Content-Type: application/json { "authn_params_public_key": { "challenge": "{GENERATED_CHALLENGE_FOR_THIS_SESSION}", "timeout": {AUTH_TIMEOUT_IN_MILLISECONDS}, "rpId": "{CUSTOM_DOMAIN}", "userVerification": "preferred" }, "auth_session": "{SESSION_ID}" } ``` #### Remarks * After the challenge request is complete, your application can continue the login process using native [Android](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) or [iOS](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) APIs. * You must then [authenticate the existing user](#authenticate-existing-user) using information retrieved through the native APIs to complete the flow. ### Authenticate Existing User `POST /oauth/token` Uses the Token endpoint to authenticate the user with the provided credentials and return the requested tokens. The `authn_response` parameter is based on the [Web Authentication API specification](https://www.w3.org/TR/webauthn-3/). In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs: * [Android login documentation](https://developer.android.com/identity/passkeys/sign-in-with-passkeys) * [iOS login documentation](https://developer.apple.com/documentation/authenticationservices/supporting-passkeys#Connect-to-a-service-with-an-existing-account) #### Request Parameters | Parameter | Description | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `grant_type` | **Required**. Include the value: `urn:okta:params:oauth:grant-type:webauthn` | | `client_id` | **Required**. The `client_id` of your application | | `realm` | **Optional**. The name of the connection to associate with the user. If a connection is not specified, your tenant's default directory is used. | | `scope` | **Optional**. Use `openid` to get an ID token or `openid profile email` to include user profile information in the ID token. | | `audience` | **Optional**. API identifier of the API for which you want to get an access token. | | `auth_session` | **Required**. Session ID returned during the initial passkey challenge request. | | `authn_response` | **Required**. An object containing the following items: | | `authn_response.id` | **Required**. Base64URL credential ID. | | `authn_response.rawId` | **Required**. Base64URL credential ID. | | `authn_response.type` | **Required**. Include the value: `public-key` | | `authn_response.authenticatorAttachment` | **Optional**. Include the values: | | `authn_response.response` | **Required**. An object containing the following items: | | `authn_response.clientExtensionResults` | **Optional**. Contains results of processing client extensions requested by the relying party. | #### Code Samples ##### Request ```text lines theme={null} 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": "{OPTIONAL_REQUESTED_SCOPE}", "audience": "{OPTIONAL_REQUESTED_AUDIENCE}" "auth_session": "{SESSION_ID_FROM_THE_FIRST_REQUEST}", "authn_response": { "id": "{BASE64URL_ID}", "rawId": "{BASE64URL_RAWID}", "type": "public-key", "authenticatorAttachment": "platform|cross-platform", "response": { "authenticatorData": "{BASE64URL_AUTHENTICATORDATA}", "clientDataJSON": "{BASE64URL_CLIENTDATAJSON}", "signature": "{BASE64URL_SIGNATURE}", "userHandle": "{BASE64URL_USERHANDLE}" }, "clientExtensionResults": {OPTIONAL_OBJECT} }, } ``` ##### Response ```json lines theme={null} HTTP/1.1 200 OK Content-Type: application/json { "access_token": "{BASE64_TOKEN}", "refresh_token": "{BASE64_TOKEN}", "id_token": "{BASE64_TOKEN}", "token_type": "Bearer", "expires_in": {SECONDS} } ```