Skip to content

feat: add Passkey APIs to Authentication API reference#1373

Merged
avanscoy merged 7 commits into
auth0:mainfrom
tomauth0:passkey-api-on-authn
Jun 17, 2026
Merged

feat: add Passkey APIs to Authentication API reference#1373
avanscoy merged 7 commits into
auth0:mainfrom
tomauth0:passkey-api-on-authn

Conversation

@tomauth0

Copy link
Copy Markdown
Contributor

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.

tomauth0 and others added 2 commits June 11, 2026 11:30
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>
@tomauth0 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
# 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>
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
</ParamField>

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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx
Comment thread main/docs/api/authentication/passkey/challenge.mdx
hazel-nut
hazel-nut previously approved these changes Jun 16, 2026

@hazel-nut hazel-nut left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, just some alignment with the existing auth api docs :)

Comment thread main/docs/api/authentication/passkey/challenge.mdx
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/challenge.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Comment thread main/docs/api/authentication/passkey/register.mdx Outdated
Co-authored-by: Hazel Virdó <github@virdo.name>
@avanscoy avanscoy merged commit 9b29aeb into auth0:main Jun 17, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants