Resources
🤖 For AI agents: The complete documentation index is available at /docs/llms.txt. A markdown version of this page is available at /docs/apis/webauthn/start-a-webauthn-passkey-registration.md.

Start a WebAuthn Passkey Registration

Edit on GitHub
View Markdown

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#

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 String optional

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#

displayName String required

The primary display name for the new passkey.

name String optional

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 String optional

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

userId UUID required

The Id of the user registering the passkey.

workflow String required

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
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty.
503The 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.

options Object

The WebAuthn public key credential creation options. This object is passed to the WebAuthn JavaScript 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 for details on converting this value for the WebAuthn JavaScript 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 for details on converting these values for the WebAuthn JavaScript 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. 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 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 for details on converting this value for the WebAuthn JavaScript 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

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