Native Passkeys API - Auth0 Docs

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. The passkey signup flow supports Organizations through the organization parameter, following the behavior described in 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 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>",
  }
}

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

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

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

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

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

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

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. The passkey login flow supports Organizations through the organization parameter, following the behavior described in 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 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

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

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

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

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

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

​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

Signup Flow

Request Signup Challenge

Request Parameters

Code Samples

Remarks

Authenticate New User

Request Parameters

Code Samples

Enrollment Flow

Initiate Passkey Enrollment

Request Parameters

Code Samples

Remarks

Verify Passkey Enrollment

Request Parameters

Code Samples

Remarks

Login Flow

Request Login Challenge

Request Parameters

Code Samples

Remarks

Authenticate Existing User

Request Parameters

Code Samples