Native Passkeys API

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

Signup Flow

Request Signup Challenge

POST /passkey/register

Initiates the passkey signup flow for a new user. In response, Auth0 returns PublicKeyCredentialCreationOptions and a session ID.

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

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?

/

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 and a session ID.

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.

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

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?

/