> ## Documentation Index
> Fetch the complete documentation index at: https://docs-dev-docs-event-stream-action-templates.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Register a New User With a Passkey

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

## Endpoint

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

### Remarks

* The application's [grant types](/docs/get-started/applications/application-settings#grant-types) must include: `urn:okta:params:oauth:grant-type:webauthn`.
* The application must be a [first-party application](https://auth0.com/docs/get-started/applications/confidential-and-public-applications). Third-party applications are not allowed to call this endpoint.
* 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.
* `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`.

## Request Body

<ParamField body="client_id" type="string" required>
  The `client_id` of your application.
</ParamField>

<ParamField body="client_secret" type="string">
  The `client_secret` of your application. Required for confidential applications using the `client_secret_post` token endpoint authentication method.
</ParamField>

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

<ParamField body="organization" type="string">
  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`.
</ParamField>

<ParamField body="user_profile" type="object" required>
  Profile attributes for the new user. Properties must match the signup attributes (`required` and `optional`) configured on the database connection. Unrecognized properties cause the request to fail with `invalid_request`.

  <Expandable title="properties">
    <ParamField body="email" type="string">
      User's email address.
    </ParamField>

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

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

    <ParamField body="name" type="string">
      Full name (1–300 characters).
    </ParamField>

    <ParamField body="given_name" type="string">
      Given name (1–150 characters).
    </ParamField>

    <ParamField body="family_name" type="string">
      Family name (1–150 characters).
    </ParamField>

    <ParamField body="nickname" type="string">
      Nickname (1–300 characters).
    </ParamField>

    <ParamField body="picture" type="string">
      URL pointing to the user's profile picture.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="user_metadata" type="object">
  Optional user metadata to attach to the new user. Up to 10 string fields.
</ParamField>

## Response

A successful response contains the WebAuthn creation parameters and an `auth_session` value that ties the subsequent attestation to this registration request.

<ResponseField name="auth_session" type="string">
  Opaque session identifier. Pass it in the token exchange request that completes the passkey registration.
</ResponseField>

<ResponseField name="authn_params_public_key" type="object">
  WebAuthn `PublicKeyCredentialCreationOptions` to invoke on the platform authenticator.

  <Expandable title="properties">
    <ResponseField name="challenge" type="string">
      Auth0-generated challenge the authenticator must sign during attestation.
    </ResponseField>

    <ResponseField name="timeout" type="integer">
      Lifetime of the challenge in milliseconds.
    </ResponseField>

    <ResponseField name="rp" type="object">
      Relying party identity.

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Relying party identifier (RP ID). Defaults to the tenant custom domain or the configured custom Relying party identifier.
        </ResponseField>

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

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

      <Expandable title="properties">
        <ResponseField name="id" type="string">
          Server-generated user handle.
        </ResponseField>

        <ResponseField name="name" type="string">
          User-facing identifier (typically the highest-precedence value supplied in `user_profile`, such as `email`).
        </ResponseField>

        <ResponseField name="displayName" type="string">
          Display name (`user_profile.name` if provided, otherwise the chosen identifier).
        </ResponseField>
      </Expandable>
    </ResponseField>

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

    <ResponseField name="authenticatorSelection" type="object">
      Authenticator selection criteria.

      <Expandable title="properties">
        <ResponseField name="residentKey" type="string">
          Resident key requirement. Always returns `required`.
        </ResponseField>

        <ResponseField name="userVerification" type="string">
          User verification requirement. Always returns `preferred`.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

| Status | Description                                                                                                                                                                                                                                                                                                                        |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200    | Registration challenge generated successfully.                                                                                                                                                                                                                                                                                     |
| 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.                                                                                                                                                                                                                                                                                     |