Verify Passkeys Client Library Technical Overview

• Service: an organization or environment (e.g. stage, prod). Contains configurations for all verification methods available through the Verify platform (SMS OTP, Voice OTP, Email OTP, Push Verification, TOTP, Passkeys). A Twilio [sub]account can have multiple Services. Each Service contains multiple Entities that are not shared across Services.
• Entity: a user or other identity that needs verification. An Entity can contain multiple Factors.
• Factor: a verification method, which involves an exchange of secrets via a communication channel. For factor_type passkeys, which is based on public-key cryptography, the Factor contains the public key of the private-public keypair generated by a registered device along with its metadata. A Factor contains multiple Challenges.
• Challenge: a single verification attempt of an Entity using a Factor. A single Factor has multiple Challenges.

The system follows a client-server architecture where the client generates or receives Passkeys and communicates with the server for verification.

Verify Passkeys involves two main sequences that are shown in the diagrams below:

Passkeys creation and registration: Register (sign up) a user by creating a unique passkey.

Passkeys Authentication: Verify (sign in) the user by authenticating the registered passkey.

When creating a passkey, the relying party (the website or application) defines the Relying Party Criteria and the Authenticator Criteria. The first step in using Verify Passkeys, is to configure the Verify service in your Twilio tenant. You can create a new service or update an existing one. The following section explains the role of each attribute in the configuration and the optional values. You can find API examples in the Passkeys API reference.

When implementing passkeys, the Relying Party must configure certain criteria to define how passkeys are created and authenticated. These settings, which are part of the WebAuthn API, allow the Relying Party to balance user experience, convenience, and security.

The RP ID is a domain string that identifies the online service during passkey registration and authentication.

• Domain-scoped: An RP ID can be a specific domain (e.g., https://www.login.example.com) or a registrable suffix (e.g., https://www.example.com).
• Subdomain access: By setting the RP ID to a domain suffix like example.com, passkeys registered on login.example.com can also be used for authentication on other subdomains, such as auth.example.com.
• Anti-phishing: The binding of a passkey to a specific RP ID is a key feature that makes it phishing-resistant. The browser enforces this binding, ensuring a passkey for example.com can't be used on a phishing site like examp1e.com.

The name of the Relying Party, for example, "My Company". This field is optional and can be set to an empty string.

An optional list of origin URLs that can be configured for strict matching. For example, you can configure Relying Party origin to allow login from login.example.com, auth.example.com but not from partners.example.com.

The Authenticator criteria specify which types of authenticators and verification methods are acceptable. These settings are based on the WebAuthn standard and help the relying party enforce its security policies.

The primary options for authenticator criteria are:

• Authenticator attachment modality.
• User verification requirement.
• Discoverable credentials (Resident key) requirement.

This criterion determines whether the authenticator must be permanently attached to the client device or can be used across multiple devices.

• Platform: A platform authenticator is integrated into the client device, such as a laptop or smartphone. For example, Apple's Touch ID and Face ID, Windows Hello, and Android's fingerprint and screen lock.
• Cross-platform: A roaming authenticator is portable and can be used across different client devices. This provides flexibility but requires the user to have the physical authenticator with them. For example, a hardware security key (e.g., a YubiKey) that connects via USB, NFC, or Bluetooth.
• Any (no preference): This is the default setting, allowing the user to register any type of authenticator.

This setting dictates whether the relying party requires a specific user verification method, such as a biometric scan or a PIN. The authentication is two-factor by design, combining something you have (the passkey on the device) with a verification step (something you are or something you know).

• Required: The authenticator must verify the user, and the operation will fail if this is not possible.
• Preferred: The authenticator should attempt user verification if possible but can proceed without it. This is the standard, user-friendly value.
• Discouraged: The authenticator should not prompt for user verification. While Verify Passkeys allow this option, it is not recommended configuring the service with Discouraged.

This option specifies whether the created passkey is discoverable, allowing users to authenticate without entering their username.

• Required: The authenticator must create a discoverable key, allowing for a username-free login experience.
• Preferred: The authenticator should attempt to create a discoverable key but can fall back to a non-discoverable key if necessary.
• Discouraged: The authenticator must create a non-discoverable key. In this case, the user must provide a username before the passkey can be used.

Check out the quickstart for step-by-step instructions.