Complete a WebAuthn Passkey Registration

Edit on GitHubEdit MD

This API is used to complete a WebAuthn registration ceremony by providing the values returned from the WebAuthn JavaScript API call. The API will validate the request against configured passkey requirements for the workflow and the one-time challenge generated and returned by Start a WebAuthn Passkey Registration.

Request#

Complete a WebAuthn Registration Ceremony and Return Passkey Details

POST/api/webauthn/register/complete

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#

The credential in the request body contains data returned by the WebAuthn JavaScript API call. The credential.response.attestationObject and credential.response.clientDataJSON fields must be converted to base64url-encoded strings for the FusionAuth API request. See WebAuthn JavaScript API Binary Format for details.

credential.clientExtensionResults.credProps.rk Boolean optional

If true, the new passkey is "client-side discoverable," meaning that it can be used in authentication ceremonies without first identifying the user (e.g. by requiring the user to complete a form field). If false, or the credential.clientExtensionResults.credProps field is omitted, the passkey should be treated as if it were not client-side discoverable. FusionAuth does not currently support discoverable credentials (sometimes referred to as "resident keys").

credential.id String required

A base64url-encoded version of the credential Id generated by the authenticator for this passkey.

credential.rpId String optional

If the tenant configuration overrides the Relying Party Id, this parameter should match tenant.webAuthnConfiguration.relyingPartyId, otherwise the value should be omitted from the request object.

credential.response.attestationObject String required

The base64url-encoded attestation data from the WebAuthn JavaScript API response, which includes information on the new passkey and other data important for validation. See Converting ArrayBuffer to base64url-encoded String for details on converting this value for the FusionAuth API request.

credential.response.clientDataJSON String required

The base64url-encoded client data from the WebAuthn JavaScript API response. This contains important information for the WebAuthn registration validation process, including the one-time challenge generated when the registration ceremony began. See Converting ArrayBuffer to base64url-encoded String for details on converting this value for the FusionAuth API request.

credential.transports Array<String> optional

A list of transport types supported by the authenticator that generated the passkey. This value is used as a hint to help identify eligible authenticators during a WebAuthn ceremony.

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

credential.type String required

The credential type of the new passkey. The only value supported by WebAuthn is public-key.

origin String optional

Ignored since 1.69.0. Instead, FusionAuth validates the origin from the signed WebAuthn client data.

Deprecated since 1.69.0

This field is required prior to version 1.69.0. The browser request origin during the registration ceremony.

rpId String optional

Ignored since 1.69.0. Instead, FusionAuth resolves the Relying Party Id from the tenant configuration and validates the Id against the signed authenticator data.

Deprecated since 1.69.0

This field is required prior to version 1.69.0. If the tenant configuration overrides the Relying Party Id, this parameter should match tenant.webAuthnConfiguration.relyingPartyId, otherwise the value should be the browser request origin's effective domain during the ceremony.

userId UUID required

The unique Id of the user registering this new passkey.

Example Request JSON

{
  "credential": {
    "clientExtensionResults": {
      "credProps": {
        "rk": true
      }
    },
    "id": "HdN9wqP9mqOonacmiM2gIjASFYg",
    "response": {
      "attestationObject": "v2dhdHRTdG109mhhdXRoRGF0YViemPsv4VW-wth0V9gzsxWRFn-1SyC9gM4-QC4ptMFDNhVFAAAAFmhGAxjmXUwbl-q5EoJkWH0AELmJieDlA5kNXEtcIgWnp1a_YTMmYTECYi0xAWItMlggTmZZ1aeY0PP8-Ebdufqcg9TWEs_mJaFJmJ57uRyQ1BxiLTNYIQCzqsN1dkCeZKpWGKEVP0-eqBlkKGNCjfcdg5221SRZX_9jZm10ZG5vbmX_",
      "clientDataJSON": "eyJjaGFsbGVuZ2UiOiJ2dHk0WG1ES01EMmxTc2dVOEpsOFlIVEtBcGZlWXpMdkRVUksxTXpGd1JvIiwiY3Jvc3NPcmlnaW4iOmZhbHNlLCJvcmlnaW4iOiJodHRwczovL2Z1c2lvbmF1dGguaW8iLCJ0eXBlIjoid2ViYXV0aG4uY3JlYXRlIn0="
    },
    "transports": [
      "internal"
    ],
    "type": "public-key"
  },
  "origin": "https://auth.piedpiper.com",
  "rpId": "piedpiper.com",
  "userId": "703fe2d2-2d39-4cb7-b76d-0b9918ed2457"
}

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

credential.algorithm Long

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

Supported algorithms

Name	Value	Description
RS256	-257	RSASSA-PKCS1-v1_5 using SHA-256
RS384	-258	RSASSA-PKCS1-v1_5 using SHA-384
RS512	-259	RSASSA-PKCS1-v1_5 using SHA-512
PS256	-37	RSASSA-PSS w/ SHA-256
PS384	-38	RSASSA-PSS w/ SHA-384
PS512	-39	RSASSA-PSS w/ SHA-512
ES256	-7	ECDSA w/ SHA-256
ES384	-35	ECDSA w/ SHA-384
ES512	-36	ECDSA w/ SHA-512

credential.attestationType String

The type of attestation provided when the passkey was registered. Passkeys registered in FusionAuth will have a value of none. Imported passkeys may have another value.

credential.authenticatorSupportsUserVerification Boolean

Indicates whether this authenticator supports user verification. User verification ensures that the user is authorized to use the authenticator.

This value is currently determined by whether user verification occurred during the registration of this passkey rather than by other means, such as examining FIDO authenticator metadata.

credential.credentialId String

The credential Id generated by the authenticator is stored as a base64url-encoded string. This value is used by authenticators to look up a passkey during an authentication ceremony and to prevent multiple passkeys from being registered on the same authenticator for a single user.

credential.data Object

An object that can hold any information about the passkey that should be persisted.

credential.discoverable Boolean

Indicates whether the passkey is "client-side discoverable." Discoverable passkeys can be used in authentication ceremonies without first identifying the user (e.g. by requiring the user to complete a form field).

credential.displayName String

The display name for the passkey selected during registration. This value should have been selected by the user.

credential.id UUID

The unique identifier for this passkey.

credential.insertInstant Long

The instant that the passkey was added to the FusionAuth database.

credential.lastUseInstant Long

The instant that the passkey was last used to complete a WebAuthn ceremony.

credential.name String

A unique name meant to disambiguate passkeys with the same credential.displayName.

credential.publicKey String

The passkey's public key, encoded in PEM format.

credential.relyingPartyId String

The Relying Party Id used at the time the passkey was registered.

credential.signCount Integer

A signature counter for the passkey. The signature count can be used by a Relying Party to identify a cloned or malfunctioning authenticator.

credential.tenantId UUID

The Id of the tenant to which this passkey belongs.

credential.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 eligible authenticators during a WebAuthn ceremony.

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

credential.userAgent String

The user agent at the time the passkey was registered. This can be useful for troubleshooting purposes.

credential.userId UUID

The Id of the user that this passkey belongs to.

Example Response JSON

{
  "credential": {
    "algorithm": -7,
    "attestationType": "none",
    "authenticatorSupportsUserVerification": true,
    "credentialId": "HdN9wqP9mqOonacmiM2gIjASFYg",
    "data": {},
    "displayName": "Chrome Touch ID",
    "name": "richard@fusionauth.io",
    "id": "c664318a-2384-4c35-9475-9a200e1d3b72",
    "insertInstant": 1668011701792,
    "discoverable": false,
    "lastUseInstant": 1668021630599,
    "publicKey": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEz9DI9AQfZn1aDJG5sw3Ckl7SoQ7E\nLPElDoJMijphvVigTcNMTc8H9Xptl8B20QHMOXGTzaUxLGNY1c8yhw9VVA==\n-----END PUBLIC KEY-----",
    "relyingPartyId": "piedpiper.com",
    "signCount": 41,
    "tenantId": "30663132-6464-6665-3032-326466613934",
    "transports": [
      "internal"
    ],
    "userId": "703fe2d2-2d39-4cb7-b76d-0b9918ed2457"
  }
}