feat: add Passkey APIs to Authentication API reference by tomauth0 · Pull Request #1373 · auth0/docs-v2

tomauth0 · 2026-06-11T11:36:34Z

Description

Adds reference documentation for the new Passkey APIs (POST /passkey/challenge
and POST /passkey/register) under the Authentication API, in support of the
Embedded Capabilities GA relaunch (Passkey APIs going GA — covers native iOS,
native Android, and web).

What's in this PR:

main/docs/api/authentication/passkey/challenge.mdx — documents
POST /passkey/challenge. Covers the request body (client_id,
client_secret, realm, organization), prerequisites (custom domain,
first-party + OIDC-conformant client, passkey grant enabled), and the
WebAuthn PublicKeyCredentialRequestOptions returned in
authn_params_public_key alongside the auth_session value used in the
subsequent token exchange.
main/docs/api/authentication/passkey/register.mdx — documents
POST /passkey/register. Covers user_profile signup attributes and
validation rules, user_metadata constraints (max 10 fields, reserved
field-name blocklist), and the WebAuthn PublicKeyCredentialCreationOptions
returned (rp, user, pubKeyCredParams, authenticatorSelection).
main/config/navigation/generated/authentication.en.json — adds a new
"Passkeys" group between "Passwordless" and "Device Authorization" that
links to both new pages.

Testing

Run mint dev from main/ and confirm:
- The "Passkeys" group appears in the Authentication API navigation between
  "Passwordless" and "Device Authorization".
- Both /passkey/challenge and /passkey/register pages render with
  parameter, response field, and status code tables.
- Internal links to Passkeys, Configure Passkey Policy, and Custom Domains
  resolve.

Checklist

I've read and followed CONTRIBUTING.md.
I've tested the site build for this change locally.
I've made appropriate docs updates for any code or config changes.
I've coordinated with the Product Docs and/or Docs Management team about non-trivial changes.

Add the missing main/docs/api/authentication/passkey/register.mdx that should have been part of the previous commit, and remove main/docs/authenticate/login/embedded-login/use-cases/enrollment.mdx, which was committed by mistake and is out of scope for this PR. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

# Conflicts: # main/config/navigation/generated/authentication.en.json

Remove the manually-edited authentication.en.json from this PR. The Passkey API pages are added as content-only; navigation will be handled separately through the OAS-generated nav pipeline. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

avanscoy · 2026-06-11T13:43:08Z

@@ -0,0 +1,79 @@
+---
+title: "Start a Passkey Challenge"
+description: "Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey."


Suggested change

description: "Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey."

description: "Request a passkey challenge for users to authenticate to your Native or Web application using an existing, registered passkey."

avanscoy · 2026-06-11T13:49:18Z

+
+`POST /passkey/challenge`
+
+Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your client uses to invoke the platform authenticator, along with an `auth_session` value that you exchange for tokens at `/oauth/token` using the passkey grant.


Suggested change

Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your client uses to invoke the platform authenticator, along with an `auth_session` value that you exchange for tokens at `/oauth/token` using the passkey grant.

Request a passkey challenge so a user can authenticate to your Native or Web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your application uses to invoke the platform authenticator, and an `auth_session` value you exchange for tokens at `/oauth/token` using the passkey grant.

avanscoy · 2026-06-11T13:50:44Z

+
+Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your client uses to invoke the platform authenticator, along with an `auth_session` value that you exchange for tokens at `/oauth/token` using the passkey grant.
+
+This endpoint backs the Passkey APIs for native and web applications and is used in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.


Suggested change

This endpoint backs the Passkey APIs for native and web applications and is used in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.

This endpoint backs the Passkey APIs for Native and Web applications. Use this endpoint in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.

avanscoy · 2026-06-11T13:51:00Z

+
+This endpoint backs the Passkey APIs for native and web applications and is used in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.
+
+### Remarks


Suggested change

### Remarks

## Remarks

avanscoy · 2026-06-11T13:54:19Z

+
+### Remarks
+
+- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.


Suggested change

- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.

- The application's [grant types](/docs/get-started/applications/application-settings#grant-types) must include: `urn:okta:params:oauth:grant-type:webauthn`.

avanscoy · 2026-06-11T13:55:46Z

+- The application must be OIDC conformant.
+- The request must be made against a [custom domain](https://auth0.com/docs/customize/custom-domains) configured for your tenant. Calls to the default Auth0 domain (`{tenant}.auth0.com`) are rejected.
+
+### Learn More


The Learn more section should be at the end of the article starting on line 81 to be consistent with the rest of Docs.

avanscoy · 2026-06-11T13:58:45Z

+</ParamField>
+
+<ParamField body="realm" type="string">
+  Name of the database connection to authenticate against. If omitted, the tenant's default database connection for the application is used.


Suggested change

Name of the database connection to authenticate against. If omitted, the tenant's default database connection for the application is used.

Name of the database connection to authenticate against. If omitted, Auth0 uses your tenant's default database connection for the application.

avanscoy · 2026-06-11T14:00:20Z

+</ParamField>
+
+<ParamField body="organization" type="string">
+  ID of the [organization](https://auth0.com/docs/manage-users/organizations) the user is signing in to. Required when the application's `organization_usage` is set to `require`.


Suggested change

ID of the [organization](https://auth0.com/docs/manage-users/organizations) the user is signing in to. Required when the application's `organization_usage` is set to `require`.

ID of the [Auth0 Organization](https://auth0.com/docs/manage-users/organizations) to which the user is signing in. Required when the application's `organization_usage` is set to `require`.

avanscoy · 2026-06-11T14:00:48Z

+
+## Response
+
+A successful response contains the WebAuthn parameters your client passes to the platform authenticator and an `auth_session` value that ties the subsequent assertion to this challenge.


Suggested change

A successful response contains the WebAuthn parameters your client passes to the platform authenticator and an `auth_session` value that ties the subsequent assertion to this challenge.

A successful response contains the WebAuthn parameters your application passes to the platform authenticator and an `auth_session` value that ties the subsequent assertion to this challenge.

avanscoy · 2026-06-11T14:04:54Z

+    </ResponseField>
+
+    <ResponseField name="rpId" type="string">
+      Relying Party identifier. Defaults to the tenant custom domain. When the tenant has a custom Relying Party identifier configured, that value is returned instead.


Suggested change

Relying Party identifier. Defaults to the tenant custom domain. When the tenant has a custom Relying Party identifier configured, that value is returned instead.

[Relying party identifier(RP ID)](/docs/authenticate/database-connections/passkeys#relying-party-id-for-passkeys). Defaults to the tenant custom domain. When the tenant has a custom relying party identifier configured, Auth0 returns the `rp.id` value instead.

avanscoy · 2026-06-11T14:06:48Z

@@ -0,0 +1,163 @@
+---
+title: "Register a New User With a Passkey"
+description: "Initiate passkey registration for a new user during sign up. Returns the WebAuthn creation parameters and an auth_session used to complete enrollment."


Suggested change

description: "Initiate passkey registration for a new user during sign up. Returns the WebAuthn creation parameters and an auth_session used to complete enrollment."

description: "Initiate passkey registration for a new user during sign up. Returns the WebAuthn creation parameters and the `auth_session` users need to complete enrollment."

avanscoy · 2026-06-11T14:14:07Z

+
+`POST /passkey/register`
+
+Initiate passkey registration for a new user during sign up. The endpoint creates a passkey enrollment session, validates the supplied user profile against the database connection's signup attributes, and returns the WebAuthn creation parameters your client passes to the platform authenticator. After the authenticator returns an attestation, you complete enrollment by exchanging the assertion at `/oauth/token` using the passkey grant.


Suggested change

Initiate passkey registration for a new user during sign up. The endpoint creates a passkey enrollment session, validates the supplied user profile against the database connection's signup attributes, and returns the WebAuthn creation parameters your client passes to the platform authenticator. After the authenticator returns an attestation, you complete enrollment by exchanging the assertion at `/oauth/token` using the passkey grant.

Initiate passkey registration for a new user during sign up. The endpoint creates a passkey enrollment session, validates the supplied user profile against the database connection's signup attributes, and returns the WebAuthn creation parameters your application passes to the platform authenticator. After the authenticator returns an attestation, you complete enrollment by exchanging the assertion at `/oauth/token` using the passkey grant.

avanscoy · 2026-06-11T14:14:18Z

+
+Initiate passkey registration for a new user during sign up. The endpoint creates a passkey enrollment session, validates the supplied user profile against the database connection's signup attributes, and returns the WebAuthn creation parameters your client passes to the platform authenticator. After the authenticator returns an attestation, you complete enrollment by exchanging the assertion at `/oauth/token` using the passkey grant.
+
+### Remarks


Suggested change

### Remarks

## Remarks

You skipped over H2

avanscoy · 2026-06-11T14:15:21Z

+
+### Remarks
+
+- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.


Suggested change

- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.

- The application's [grant types](/docs/get-started/applications/application-settings#grant-types) must include: `urn:okta:params:oauth:grant-type:webauthn`.

avanscoy · 2026-06-11T14:15:47Z

+- `user_profile` must contain every identifier marked `required` for signup on the connection (commonly `email`, `phone_number`, or `username`). Additional identifiers may be `optional`.
+- A user is identified as already-existing through any of the configured identifiers; if any submitted identifier resolves to an existing user, the request fails with `invalid_request`.
+
+### Learn More


Move line 19-23 to the end of the article to be consisten with Docs

avanscoy · 2026-06-11T14:17:01Z

+</ParamField>
+
+<ParamField body="realm" type="string">
+  Name of the database connection the user is signing up against. If omitted, the tenant's default database connection for the application is used.


Suggested change

Name of the database connection the user is signing up against. If omitted, the tenant's default database connection for the application is used.

Name of the database connection the user is signing up against. If omitted, Auth0 uses your tenant's default database connection for the application.

avanscoy · 2026-06-11T14:20:15Z

+</ParamField>
+
+<ParamField body="organization" type="string">
+  ID of the [organization](https://auth0.com/docs/manage-users/organizations) the user is signing up into. Required when the application's `organization_usage` is set to `require`.


Suggested change

ID of the [organization](https://auth0.com/docs/manage-users/organizations) the user is signing up into. Required when the application's `organization_usage` is set to `require`.

ID of the [Auth0 Organization](https://auth0.com/docs/manage-users/organizations) to which the user is signing in. Required when the application's `organization_usage` is set to `require`.

avanscoy · 2026-06-11T14:20:52Z

+
+  <Expandable title="properties">
+    <ParamField body="email" type="string">
+      User's email address. Validated against the JSON Schema email format.


Suggested change

User's email address. Validated against the JSON Schema email format.

User's email address. Validated against the `JSON` schema email format.

avanscoy · 2026-06-11T14:22:40Z

+    </ParamField>
+
+    <ParamField body="phone_number" type="string">
+      User's phone number in E.164 format (1–30 characters, international `+` prefix).


avanscoy · 2026-06-11T14:23:35Z

+    </ParamField>
+
+    <ParamField body="username" type="string">
+      User's username. Validated against the connection's username policy (length and allowed characters).


Suggested change

User's username. Validated against the connection's username policy (length and allowed characters).

User's username. Validates against the connection's username policy (length and allowed characters).

avanscoy · 2026-06-11T14:27:31Z

+    </ResponseField>
+
+    <ResponseField name="rp" type="object">
+      Relying Party identity.


Suggested change

Relying Party identity.

Relying party identity.

avanscoy · 2026-06-11T14:28:14Z

+
+      <Expandable title="properties">
+        <ResponseField name="id" type="string">
+          Relying Party identifier. Defaults to the tenant custom domain or the configured custom Relying Party identifier.


Suggested change

Relying Party identifier. Defaults to the tenant custom domain or the configured custom Relying Party identifier.

Relying party identifier (RP ID). Defaults to the tenant custom domain or the configured custom Relying party identifier.

avanscoy · 2026-06-11T14:28:36Z

+        </ResponseField>
+
+        <ResponseField name="name" type="string">
+          Relying Party display name. Returned identical to `rp.id`.


Suggested change

Relying Party display name. Returned identical to `rp.id`.

Relying party display name. Returned identical to `rp.id`.

avanscoy · 2026-06-11T14:34:21Z

+    </ResponseField>
+
+    <ResponseField name="user" type="object">
+      WebAuthn user handle to bind the new credential to.


Suggested change

WebAuthn user handle to bind the new credential to.

WebAuthn user handle to which you bind the new credential.

avanscoy · 2026-06-11T14:35:46Z

+    </ResponseField>
+
+    <ResponseField name="pubKeyCredParams" type="array">
+      Allowed credential public-key algorithms in preference order. Auth0 returns EdDSA (`-8`), ES256 (`-7`), and RS256 (`-257`).


Suggested change

Allowed credential public-key algorithms in preference order. Auth0 returns EdDSA (`-8`), ES256 (`-7`), and RS256 (`-257`).

Allowed credential [public-key algorithms](/docs/get-started/applications/signing-algorithms) in preference order. Auth0 returns EdDSA (`-8`), ES256 (`-7`), and RS256 (`-257`).

avanscoy · 2026-06-11T14:37:09Z

+| 400 | Invalid request. Common causes include missing required `user_profile` identifiers, an invalid `user_profile` field, an invalid `user_metadata` field, the user already exists, the application is not configured for passkey authentication, the request was not made against a custom domain, or the application is third-party. |
+| 401 | Unauthorized. Invalid client credentials. |
+| 404 | The Passkey APIs are not enabled for the tenant. |
+| 429 | Too many requests. Per-IP rate limit exceeded. |


Suggested change

| 429 | Too many requests. Per-IP rate limit exceeded. |

| 429 | Too many requests. Per-IP rate limit exceeded. |

## Learn more

- [Passkeys APIs](https://auth0.com/docs/authenticate/database-connections/passkeys/native-passkeys-api)

- [Configure Passkey Policy](https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkey-policy)

- [Custom Domains](https://auth0.com/docs/customize/custom-domains)

avanscoy · 2026-06-11T14:37:38Z

+| 400 | Invalid request. Common causes include missing or invalid parameters, the application is not configured for passkey authentication, the request was not made against a custom domain, or the application is third-party. |
+| 401 | Unauthorized. Invalid client credentials. |
+| 404 | The Passkey APIs are not enabled for the tenant. |
+| 429 | Too many requests. Per-IP rate limit exceeded. |


Suggested change

| 429 | Too many requests. Per-IP rate limit exceeded. |

| 429 | Too many requests. Per-IP rate limit exceeded. |

## Learn more

- [Passkeys APIs](https://auth0.com/docs/authenticate/database-connections/passkeys/native-passkeys-api)

- [Configure Passkey Policy](https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkey-policy)

- [Custom Domains](https://auth0.com/docs/customize/custom-domains)

tomauth0 and others added 2 commits June 11, 2026 11:30

add Passkey APIs to Authentication API reference

6eb1c19

tomauth0 requested a review from a team as a code owner June 11, 2026 11:36

tomauth0 and others added 2 commits June 11, 2026 12:51

Merge branch 'main' into passkey-api-on-authn

919d90f

# Conflicts: # main/config/navigation/generated/authentication.en.json

avanscoy reviewed Jun 11, 2026

View reviewed changes

	description: "Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey."
	description: "Request a passkey challenge for users to authenticate to your Native or Web application using an existing, registered passkey."


		`POST /passkey/challenge`

		Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your client uses to invoke the platform authenticator, along with an `auth_session` value that you exchange for tokens at `/oauth/token` using the passkey grant.


		Request a passkey challenge so a user can authenticate to your native or web application using a previously registered passkey. The endpoint returns the WebAuthn parameters your client uses to invoke the platform authenticator, along with an `auth_session` value that you exchange for tokens at `/oauth/token` using the passkey grant.

		This endpoint backs the Passkey APIs for native and web applications and is used in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.


		This endpoint backs the Passkey APIs for native and web applications and is used in combination with the Auth0 [token exchange for passkey](https://auth0.com/docs/authenticate/database-connections/passkeys) grant type.

		### Remarks


		### Remarks

		- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.

	- The application's grant types must include `urn:okta:params:oauth:grant-type:webauthn`.
	- The application's [grant types](/docs/get-started/applications/application-settings#grant-types) must include: `urn:okta:params:oauth:grant-type:webauthn`.

	Name of the database connection to authenticate against. If omitted, the tenant's default database connection for the application is used.
	Name of the database connection to authenticate against. If omitted, Auth0 uses your tenant's default database connection for the application.

	ID of the [organization](https://auth0.com/docs/manage-users/organizations) the user is signing in to. Required when the application's `organization_usage` is set to `require`.
	ID of the [Auth0 Organization](https://auth0.com/docs/manage-users/organizations) to which the user is signing in. Required when the application's `organization_usage` is set to `require`.


		## Response

		A successful response contains the WebAuthn parameters your client passes to the platform authenticator and an `auth_session` value that ties the subsequent assertion to this challenge.

	Relying Party identifier. Defaults to the tenant custom domain. When the tenant has a custom Relying Party identifier configured, that value is returned instead.
	[Relying party identifier(RP ID)](/docs/authenticate/database-connections/passkeys#relying-party-id-for-passkeys). Defaults to the tenant custom domain. When the tenant has a custom relying party identifier configured, Auth0 returns the `rp.id` value instead.

	description: "Initiate passkey registration for a new user during sign up. Returns the WebAuthn creation parameters and an auth_session used to complete enrollment."
	description: "Initiate passkey registration for a new user during sign up. Returns the WebAuthn creation parameters and the `auth_session` users need to complete enrollment."


		`POST /passkey/register`

		Initiate passkey registration for a new user during sign up. The endpoint creates a passkey enrollment session, validates the supplied user profile against the database connection's signup attributes, and returns the WebAuthn creation parameters your client passes to the platform authenticator. After the authenticator returns an attestation, you complete enrollment by exchanging the assertion at `/oauth/token` using the passkey grant.

	Name of the database connection the user is signing up against. If omitted, the tenant's default database connection for the application is used.
	Name of the database connection the user is signing up against. If omitted, Auth0 uses your tenant's default database connection for the application.

	User's email address. Validated against the JSON Schema email format.
	User's email address. Validated against the `JSON` schema email format.

	User's username. Validated against the connection's username policy (length and allowed characters).
	User's username. Validates against the connection's username policy (length and allowed characters).

	Relying Party identifier. Defaults to the tenant custom domain or the configured custom Relying Party identifier.
	Relying party identifier (RP ID). Defaults to the tenant custom domain or the configured custom Relying party identifier.

	Relying Party display name. Returned identical to `rp.id`.
	Relying party display name. Returned identical to `rp.id`.

	WebAuthn user handle to bind the new credential to.
	WebAuthn user handle to which you bind the new credential.

	Allowed credential public-key algorithms in preference order. Auth0 returns EdDSA (`-8`), ES256 (`-7`), and RS256 (`-257`).
	Allowed credential [public-key algorithms](/docs/get-started/applications/signing-algorithms) in preference order. Auth0 returns EdDSA (`-8`), ES256 (`-7`), and RS256 (`-257`).

-| 429 | Too many requests. Per-IP rate limit exceeded. |
+| 429 | Too many requests. Per-IP rate limit exceeded. |
+## Learn more
+- [Passkeys APIs](https://auth0.com/docs/authenticate/database-connections/passkeys/native-passkeys-api)
+- [Configure Passkey Policy](https://auth0.com/docs/authenticate/database-connections/passkeys/configure-passkey-policy)
+- [Custom Domains](https://auth0.com/docs/customize/custom-domains)

Conversation

tomauth0 commented Jun 11, 2026

Description

Testing

Checklist

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avanscoy Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avanscoy Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

avanscoy Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

avanscoy Jun 11, 2026 •

edited

Loading

avanscoy Jun 11, 2026 •

edited

Loading

avanscoy Jun 11, 2026 •

edited

Loading