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 navigator.credentials.create() function and includes a one-time challenge unique to the current registration ceremony.

Request#

Start a WebAuthn Registration Ceremony and Retrieve Passkey Creation Options

POST/api/webauthn/register/start

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantIdStringoptional

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 for additional information.

Request Body#

displayNameStringrequired

The primary display name for the new passkey.

nameStringoptional

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.

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.

userAgentStringoptional

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

userIdUUIDrequired

The Id of the user registering the passkey.

workflowStringrequired

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

{
  "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 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.
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. The options.challenge, options.user.id, and options.excludeCredentials[x].id fields must be converted to ArrayBuffers for the navigator.credentials.create() request. See WebAuthn JavaScript API Binary Format for details.

optionsObject

The WebAuthn public key credential creation options. This object is passed to the WebAuthn JavaScript API to create a new passkey.

options.attestationString

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

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

options.authenticatorSelection.authenticatorAttachmentString

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

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

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 for details on converting this value for the WebAuthn JavaScript API call.

options.excludeCredentialsArray

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].idString

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 for details on converting these values for the WebAuthn JavaScript API call.

options.excludeCredentials[x].transportsArray<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].typeString

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

options.extensions.credPropsBoolean

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

options.pubKeyCredParamsArray

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].algLong

The identifier for the signing algorithm to be used with the passkey. These values are defined by the IANA COSE Algorithms registry. FusionAuth supports a subset of these algorithms.

options.pubKeyCredParams[x].typeString

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

options.rp.idString

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 will use the browser origin as the Relying Party Id.

options.rp.nameString

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

options.timeoutLong

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

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

options.user.idString

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 for details on converting this value for the WebAuthn JavaScript API call.

options.user.nameString

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

{
  "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"
    }
  }
}