Native Passkeys API

Native passkeys is currently available in limited Early Access. To learn more about Auth0 releases, review Product Release Stages.

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.

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 and are currently available in limited Early Access. To learn more about using this API, review the Authentication API Introduction.

This article describes how to perform three activities (or "flows") related to passkeys:

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.

POST /passkey/register

Initiates the passkey signup flow for a new user. In response, Auth0 returns PublicKeyCredentialCreationOptions and a session ID. Check timeout under authn_params_public_key in response for session timeout.

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

POST /passkey/register
Content-Type: application/json

{
  "client_id": "<CLIENT_ID>",
  "realm": "<OPTIONAL_CONNECTION>",
  "user_profile": {
	  "email": "<VALID_EMAIL_ADDRESS>",
	  "name": "<OPTIONAL_USER_DISPLAY_NAME>",
  }
}

Was this helpful?

Response

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>"
}

Was this helpful?

Remarks

After the challenge request is complete, your application can continue the user registration process using native Android or iOS APIs.
You must then authenticate the 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. In the native passkey flow, the information passed to this endpoint can be retrieved through your mobile application’s native APIs:

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: `id` `rawId` `type` `authenticatorAttachment` `response`
`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: `clientDataJson`: Contains JSON-compatible serialization of client data; inherited from the AuthenticatorResponse. `attestationObject`: Contains authenticator data and an attestation statement; inherited from the AuthenticatorResponse.

Code Samples

Request

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "<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>
    }  
}

Was this helpful?

Response

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

Was this helpful?

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

{
  "type": "passkey",
  "connection": "CONNECTION_NAME",
  "identity": "IDENTITY_USER_ID"
}

Was this helpful?

Response

{
  "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"
}

Was this helpful?

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

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: `clientDataJson`: Contains JSON-compatible serialization of client data; inherited from the `AuthenticatorResponse`. `attestationObject`: Contains authenticator data and an attestation statement; inherited from the `AuthenticatorResponse`.

Code Samples

Request

{
  "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"
    }
  }
}

Was this helpful?

Remarks

Once this step is completed successfully, the passkey is enrolled for the user and can be used for future authentications.

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 and a session ID. Check timeout under authn_params_public_key in response for session timeout.

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

POST /passkey/challenge
Content-Type: application/json

{
  "client_id": "<CLIENT_ID>",
  "realm": "<OPTIONAL_CONNECTION>"
}

Was this helpful?

Response

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>"
}

Was this helpful?

Remarks

After the challenge request is complete, your application can continue the login process using native Android or iOS APIs.
You must then authenticate the 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.

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: `id` `rawId` `type` `authenticatorAttachment` `response` `clientExtensionResults`
`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: `authenticatorData`: Contains authenticator data returned by the authenticator. `clientDataJson`: Contains JSON-compatible serialization of client data; inherited from the AuthenticatorResponse. `signature`: Base64URL signature returned from the authenticator. `userHandle`: Base64URL identifier for the user account, returned as `user.id` in registration step.
`authn_response.clientExtensionResults`	Optional. Contains results of processing client extensions requested by the relying party.

Code Samples

Request

POST /oauth/token
Content-Type: application/json

{
  "grant_type": "urn:okta:params:oauth:grant-type:webauthn",
  "client_id": "<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>
}

Was this helpful?

Response

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

Was this helpful?

Home

Get Started

Authenticate

Manage Users

Customize

Secure

Deploy and Monitor

Troubleshoot

Native Passkeys API

Signup Flow

Request Signup Challenge

Request Parameters

Code Samples

Request

Response

Remarks

Authenticate New User

Request Parameters

Code Samples

Request

Response

Enrollment Flow

Initiate Passkey Enrollment

Request Parameters

Code Samples

Request

Response

Remarks

Verify Passkey Enrollment

Request Parameters

Code Samples

Request

Remarks

Login Flow

Request Login Challenge

Request Parameters

Code Samples

Request

Response

Remarks

Authenticate Existing User

Request Parameters

Code Samples

Request

Response