/Docs

Retrieve a Passkey

This API is used to retrieve information about a single WebAuthn passkey or all of a user's registered passkeys.

Request#

API Key Authentication
Retrieve a single Passkey by Id
GET/api/webauthn/{id}
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 Parameters#

idUUIDrequired

The unique Id of the WebAuthn passkey to retrieve.

API Key Authentication
Retrieve all Passkeys belonging to a User
GET/api/webauthn?userId={userId}
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 Parameters#

userIdUUIDrequired

The unique Id of the User to retrieve WebAuthn passkeys for.

Response#

The response for this API contains either a single Passkey or all of the Passkeys belonging to a User. When you call this API with an Id, the response will contain just that Passkey. When you call this API without an Id and provide a User Id in the query string, the response will contain all of the Passkeys belonging to that User. Both response types are defined below along with an example JSON 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.
404The object you requested doesn't exist. The response will be empty.
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#

credential.algorithmLong

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

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

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

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

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

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

credential.discoverableBoolean

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

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

credential.idUUID

The unique identifier for this passkey.

credential.insertInstantLong

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

credential.lastUseInstantLong

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

credential.nameString

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

credential.publicKeyString

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

credential.relyingPartyIdString

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

credential.signCountInteger

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

credential.tenantIdUUID

The Id of the tenant to which this passkey belongs.

credential.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 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.userAgentString

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

credential.userIdUUID

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

Response Body#

credentials[x]Array

The list of WebAuthn Passkey objects.

credentials[x].algorithmLong

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

NameValueDescription
RS256-257RSASSA-PKCS1-v1_5 using SHA-256
RS384-258RSASSA-PKCS1-v1_5 using SHA-384
RS512-259RSASSA-PKCS1-v1_5 using SHA-512
PS256-37RSASSA-PSS w/ SHA-256
PS384-38RSASSA-PSS w/ SHA-384
PS512-39RSASSA-PSS w/ SHA-512
ES256-7ECDSA w/ SHA-256
ES384-35ECDSA w/ SHA-384
ES512-36ECDSA w/ SHA-512
credentials[x].attestationTypeString

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.

credentials[x].authenticatorSupportsUserVerificationBoolean

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.

credentials[x].credentialIdString

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.

credentials[x].dataObject

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

credentials[x].discoverableBoolean

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

credentials[x].displayNameString

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

credentials[x].idUUID

The unique identifier for this passkey.

credentials[x].insertInstantLong

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

credentials[x].lastUseInstantLong

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

credentials[x].nameString

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

credentials[x].publicKeyString

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

credentials[x].relyingPartyIdString

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

credentials[x].signCountInteger

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

credentials[x].tenantIdUUID

The Id of the tenant to which this passkey belongs.

credentials[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 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
credentials[x].userAgentString

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

credentials[x].userIdUUID

The Id of the user that this passkey belongs to.

Example Response JSON

{
  "credentials": [
    {
      "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"
    }
  ]
}