Passkey Reference

Start Passkey Registration

Initiates the passkey registration process for a user. This generates WebAuthn registration options that should be passed to your WebAuthn library on the client side.

Arguments

• userId (string, required): The ID of the user
• emailOrUsername (string, required): The email address or username of the user
• userDisplayName (string): A human-readable display name for the user
• passkeyDisplayName (string): A custom display name for the passkey being created
• additionalAllowedOrigin (string): An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

• registrationOptions (object): WebAuthn registration options to pass to your WebAuthn library

Error Types

• CannotParseAdditionalAllowedOrigin: The additionalAllowedOrigin field was not formatted correctly as a valid origin
• TooManyPasskeys: The user has reached the maximum number of passkeys allowed
• UnexpectedError: An unexpected error occurred during the operation

Example request in different programming languages:

const auth = createClient({ url, integrationKey });
const result = await auth.passkeys.startRegistration({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  emailOrUsername: "user@example.com",
  userDisplayName: "Example User",
  passkeyDisplayName: "My MacBook",
  additionalAllowedOrigin: "https://app.example.com"
});

client = create_client(url=url, integration_key=integration_key)
result = await client.passkeys.start_registration(
    user_id="1189c444-8a2d-4c41-8b4b-ae43ce79a492",
    email_or_username="user@example.com",
    user_display_name="Example User",
    passkey_display_name="My MacBook",
    additional_allowed_origin="https://app.example.com"
)

Finish Passkey Registration

Completes the passkey registration process. This should be called after the user has completed the WebAuthn registration ceremony on the client side.

Arguments

• userId (string, required): The ID of the user
• publicKeyJsonValue (required): The public key credential returned from the WebAuthn registration
• additionalAllowedOrigin (string): An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

Returns an empty response on success.

Error Types

• CannotParseAdditionalAllowedOrigin: The additionalAllowedOrigin field was not formatted correctly as a valid origin
• NoRegistrationChallengeFound: No registration challenge was found for this user
• OriginNotAllowed: The origin of the request does not match the expected origin from the registration challenge
• PasskeyForUserAlreadyExists: A passkey with this credential ID already exists for the user
• UnexpectedError: An unexpected error occurred during the operation

Example request in different programming languages:

const auth = createClient({ url, integrationKey });
const result = await auth.passkeys.finishRegistration({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  publicKey: publicKeyCredential, // from WebAuthn API
  additionalAllowedOrigin: "https://app.example.com"
});

Start Passkey Authentication

Initiates the passkey authentication process for a user. This generates WebAuthn authentication options that should be passed to your WebAuthn library on the client side.

Arguments

• userId (string, required): The ID of the user
• additionalAllowedOrigin (string): An additional origin to allow for passkey operations (beyond the default origin)

Successful Response

• authenticationOptions (object): WebAuthn authentication options to pass to your WebAuthn library

Error Types

• CannotParseAdditionalAllowedOrigin: The additionalAllowedOrigin field was not formatted correctly as a valid origin
• NoPasskeysRegisteredForUser: The user has no passkeys registered
• UnexpectedError: An unexpected error occurred during the operation

Example request in different programming languages:

const auth = createClient({ url, integrationKey });
const result = await auth.passkeys.startAuthentication({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  additionalAllowedOrigin: "https://app.example.com"
});

Deregister Passkey

Removes a specific passkey for a user.

Arguments

• userId (string, required): The ID of the user
• credentialId (string, required): The credential ID of the passkey to remove

Successful Response

Returns an empty response on success.

Error Types

• PasskeyNotFound: The specified passkey does not exist for this user
• UnexpectedError: An unexpected error occurred during the operation

Example request in different programming languages:

const auth = createClient({ url, integrationKey });
const result = await auth.passkeys.deregisterPasskey({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492",
  credentialId: "Qig5uty-0-H..."
});

Fetch All Passkeys For User

Retrieves all registered passkeys for a specific user.

Arguments

• userId (string, required): The ID of the user

Successful Response

• passkeys (array): Array of passkey information objects

Error Types

• UnexpectedError: An unexpected error occurred during the operation

Example request in different programming languages:

const auth = createClient({ url, integrationKey });
const result = await auth.passkeys.fetchAllPasskeysForUser({
  userId: "1189c444-8a2d-4c41-8b4b-ae43ce79a492"
});

Configuring Passkey Settings

You can configure passkey settings in the 'passkeys_config.jsonc' file.

Arguments

• hostname (string, required): Hostname for the WebAuthn relying party (without protocol).
• max_passkeys_per_user (number): Maximum number of passkeys allowed per user. Defaults to 5, maximum is 10.

Example JSONC configuration:

{
    "hostname": "example.com",
    "max_passkeys_per_user": 5
}