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_identifier": {
"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": "<APPLICATION_NAME>"
},
"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 |
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
POST /oauth/token
Content-Type: application/json
{
"grant_type": "urn:okta:params:oauth:grant-type:webauthn",
"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 |
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:
|
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",
"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?