> For the complete documentation index, see [llms.txt](https://fusionauth.io/docs/llms.txt)

# Start a WebAuthn Passkey Registration

API documentation for the FusionAuth Start a WebAuthn Passkey Registration API.

# Start a WebAuthn Passkey Registration

This API is used to start a WebAuthn registration ceremony by providing some details about the current user and the new passkey. The response is a JSON object which is suitable to be passed to the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) `navigator.credentials.create()` function and includes a one-time challenge unique to the current registration ceremony.

## Request

[!API Key Authentication](https://fusionauth.io/docs/apis/authentication.md#api-key-authentication)

Start a WebAuthn Registration Ceremony and Retrieve Passkey Creation Options

POST/api/webauthn/register/start

OpenAPI Spec

#### Request Headers

`X-FusionAuth-TenantId`Stringoptional

The unique Id of the tenant used to scope this API request.

The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon the request parameters or it is otherwise not required.

Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.

See [Making an API request using a Tenant Id](https://fusionauth.io/docs/apis/authentication.md#making-an-api-request-using-a-tenant-id) for additional information.

#### Request Body

`displayName`Stringrequired

The primary display name for the new passkey.

`name`Stringoptional

The optional name for the passkey. This is meant to disambiguate passkeys with the same **displayName**. When this parameter is omitted, it will be defaulted to the user's email address. If the user does not have an email address, this parameter will be defaulted to their username instead.

Prior to version `1.42.0` **name** was defaulted to a random four character alphanumeric string.

note

The passkey **name** is set at the time the passkey is registered. There is currently no way to change the name of the passkey. Prompts displayed by the WebAuthn JavaScript API will continue to display the original value at the time the passkey was registered even if the user updates their email address or username. In order to display the updated email or username the user must register a new passkey.

`userAgent`Stringoptional

The user's browser's user agent string. This value is meant for troubleshooting issues with passkeys.

`userId`UUIDrequired

The Id of the user registering the passkey.

`workflow`Stringrequired

The WebAuthn workflow this passkey is intended to be used with. Selecting the proper value will provide the best user experience by limiting the registration ceremony to authenticators which support the features needed for each workflow. The selected workflow will change the creation options on the response based on the tenant configuration. The possible values are:

*   `bootstrap` - The passkey is intended for use with the bootstrap workflow, which requires the user to "bootstrap" the authentication process by identifying themselves prior to the WebAuthn ceremony and can be used to authenticate from a new device using WebAuthn.
*   `general` - The passkey is not intended for any particular workflow. This value will allow for the most flexible use of the new passkey.
*   `reauthentication` - The passkey is intended for use with the re-authentication workflow, which provides a streamlined user experience for repeated logins from the same device.

*Example Request JSON*

```json
{
  "displayName": "Chrome Touch ID",
  "userId": "703fe2d2-2d39-4cb7-b76d-0b9918ed2457",
  "workflow": "reauthentication"
}
```

## Response

*Response Codes*

| Code | Description |
| --- | --- |
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an [Errors](https://fusionauth.io/docs/apis/errors.md) JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See [Authentication](https://fusionauth.io/docs/apis/authentication.md). |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
| 503 | The search index is not available or encountered an exception so the request cannot be completed. The response will contain a JSON body. |

#### Response Body

The response body contains `options` to be passed to the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API). The **options.challenge**, **options.user.id**, and **options.excludeCredentials`[x]`.id** fields must be converted to `ArrayBuffer`s for the `navigator.credentials.create()` request. See [WebAuthn JavaScript API Binary Format](https://fusionauth.io/docs/apis/webauthn.md#webauthn-javascript-api-binary-format) for details.

`options`Object

The WebAuthn public key credential creation options. This object is passed to the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) to create a new passkey.

`options.attestation`String

The Relying Party's attestation conveyance preference. Currently supported values include:

*   `none` - The Relying Party is not interested in authenticator attestation.

`options.authenticatorSelection.authenticatorAttachment`String

The Relying Party's authenticator attachment preference. Authenticators eligible for the current registration ceremony will be limited according to this requested attachment preference. Possible values are:

*   `platform` - The authenticator is integrated with the current device. These typically use the device's unlock mechanism for user verification (e.g. Touch ID, PIN, pattern).
*   `cross-platform` - The authenticator can be used between multiple devices such as a USB security key or Bluetooth-connected phone.
*   `null` (or omitted) - The Relying Party has no attachment preference. Any attachment will be allowed.

`options.authenticatorSelection.userVerification`String

The Relying Party's user verification requirement. Eligible authenticators will be filtered according to this preference. Possible values are:

*   `discouraged` - The Relying Party does not want user verification to be used.
*   `preferred` - The Relying Party prefers that user verification is used if available but will not fail the ceremony if it is not provided.
*   `required` - The Relying Party requires user verification for the operation.

`options.challenge`String

This field contains a base64url-encoded string that acts as a one-time challenge for the ceremony. This makes WebAuthn resistant to certain kinds of replay attacks.

See [Converting base64url-encoded String to ArrayBuffer](https://fusionauth.io/docs/apis/webauthn.md#converting-base64url-encoded-string-to-arraybuffer) for details on converting this value for the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) call.

`options.excludeCredentials`Array

A list of passkeys whose generating authenticators should be excluded from the current registration ceremony. This is meant to prevent a user creating multiple passkeys for the same account on the same authenticator.

`options.excludeCredentials[x].id`String

The credential Id generated by the authenticator as a base64url-encoded string. An available authenticator that owns any passkey with one of these Ids is excluded from the current ceremony.

See [Converting base64url-encoded String to ArrayBuffer](https://fusionauth.io/docs/apis/webauthn.md#converting-base64url-encoded-string-to-arraybuffer) for details on converting these values for the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) call.

`options.excludeCredentials[x].transports`Array<String>

A list of transport types supported by the authenticator that generated the passkey. This value is used as a hint to help identify authenticators containing one of the **options.excludeCredentials**.

FusionAuth treats the list of transports as strings to maximize authenticator compatibility. These values are used as hints during WebAuthn ceremonies and missing, extra, or unexpected values should not cause a ceremony to fail. Some common values are:

*   `internal` - the authenticator is integrated with the client device
*   `usb` - the authenticator can be contacted over USB
*   `nfc` - the authenticator can be contacted over Near Field Communication (NFC)
*   `ble` - the authenticator can be contacted over Bluetooth Smart (Bluetooth Low Energy, or BLE)
*   `cable` - "cloud-assisted" BLE. This transport is used for Android devices acting as an authenticator connected to the computer over Bluetooth
*   `hybrid` - replacement for the `cable` transport

`options.excludeCredentials[x].type`String

The credential type the current passkey refers to. The only value supported by WebAuthn is `public-key`.

`options.extensions.credProps`Boolean

If `true`, the Relying Party will request the client to report on whether the new passkey is a client-side discoverable credential.

`options.pubKeyCredParams`Array

A list of the Relying Party's acceptable options for the type of passkey and its signing algorithm in order of preference.

`options.pubKeyCredParams[x].alg`Long

The identifier for the signing algorithm to be used with the passkey. These values are defined by the [IANA COSE Algorithms registry](https://www.iana.org/assignments/cose/cose.xhtml). FusionAuth supports a subset of these algorithms.

`options.pubKeyCredParams[x].type`String

The credential type the current passkey refers to. The only value supported by WebAuthn is `public-key`.

`options.rp.id`String

The Relying Party Id for this registration ceremony. Passkeys can only be used to authenticate on sites using the same Relying Party Id they were registered with.

If this value is `null` or omitted, the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) will use the browser origin as the Relying Party Id.

`options.rp.name`String

The name of the Relying Party requesting a new passkey to be created. This value is intended for display during WebAuthn ceremonies.

`options.timeout`Long

The number of milliseconds the Relying Party is willing to wait for the ceremony to complete. This value is treated as a hint and may be overridden by the client. This is an unsigned value.

`options.user.displayName`String

A human-readable display name for the new passkey. This value may be displayed during the current and future WebAuthn ceremonies.

`options.user.id`String

A user handle that can be used by the Relying Party to uniquely identify the user registering the passkey. FusionAuth uses the base64url-encoded unique Id for the user.

See [Converting base64url-encoded String to ArrayBuffer](https://fusionauth.io/docs/apis/webauthn.md#converting-base64url-encoded-string-to-arraybuffer) for details on converting this value for the [WebAuthn JavaScript API](https://developer.mozilla.org/en-US/docs/Web/API/Web_Authentication_API) call.

`options.user.name`String

A human-readable name for the passkey intended for display. This value is meant to disambiguate between passkeys with a similar **displayName**.

*Example Response JSON*

```json
{
  "options": {
    "attestation": "none",
    "authenticatorSelection": {
      "authenticatorAttachment": "platform",
      "userVerification": "required"
    },
    "challenge": "fdnW2u1_Nk9_FY2SprU4mPs0NgBTbo9tOO5Q9EvO1Oc",
    "excludeCredentials": [
      {
        "id": "MBU0eBsaNAt4VEh4Lbn2sQ==",
        "transports": [
          "internal"
        ],
        "type": "public-key"
      }
    ],
    "extensions": {
      "credProps": true
    },
    "pubKeyCredParams": [
      {
        "alg": -36,
        "type": "public-key"
      },
      {
        "alg": -35,
        "type": "public-key"
      },
      {
        "alg": -7,
        "type": "public-key"
      },
      {
        "alg": -39,
        "type": "public-key"
      },
      {
        "alg": -38,
        "type": "public-key"
      },
      {
        "alg": -37,
        "type": "public-key"
      },
      {
        "alg": -259,
        "type": "public-key"
      },
      {
        "alg": -258,
        "type": "public-key"
      },
      {
        "alg": -257,
        "type": "public-key"
      }
    ],
    "rp": {
      "id": "piedpiper.com",
      "name": "Pied Piper"
    },
    "timeout": 180000,
    "user": {
      "displayName": "Chrome Touch ID",
      "id": "NzAzZmUyZDItMmQzOS00Y2I3LWI3NmQtMGI5OTE4ZWQyNDU3",
      "name": "richard@fusionauth.io"
    }
  }
}
```