CorbadoConnectAppend is used after a user has been authenticated (e.g., they’ve just logged in with a password or have an active session). Its role is to guide the user through creating (or “appending”) a passkey to their account if the user and their device meet the eligibility requirements.

​
When to Use This Component

This component should be loaded on any page that is shown to a user immediately after they have successfully logged in, such as a dashboard or a dedicated welcome page.

​
Rendering Logic

The component is not always visible. Before rendering its UI, it performs two critical checks. If either check fails, the component will not render, and the onSkip callback will be triggered.

  1. Initial Check (Gradual Rollout): It first determines if the current user should be offered the option to create a passkey. This is controlled by the Gradual Rollout feature, which allows you to enable passkey creation for specific user segments.
  2. Device Suitability (Passkey Intelligence): It checks if creating a passkey on the current device makes sense. This is determined by Passkey Intelligence, which assesses factors like browser support and whether the user already has a passkey on the device.
  3. User Confirmation (Explainer): If the above checks pass, it shows an “explainer” screen. This screen informs the user about the benefits of passkeys and asks for their consent before proceeding. The content of this screen can be customized.
  4. Passkey Creation: Once the user agrees, the component initiates the WebAuthn API to create and register the passkey.

​
User Experience

When the component is visible, it provides a clear call-to-action inviting the user to create a passkey for faster, more secure logins. Once rendered, the user has three possible interactions:

  1. Create a Passkey: The user can start the native browser flow to create and save a passkey.
  2. Skip for Now: The user can dismiss the prompt.
  3. Learn More: The user can view additional information about what passkeys are.

​
Error Handling

The component features built-in error handling. If an issue occurs during the passkey creation process (e.g., the user accidentally closes the browser prompt), the UI will display an informative error message and give the user the option to retry the operation.

​
Example

Important: Only authenticated users are allowed to create new passkeys. You must generate a secure ConnectToken (see here) on your backend to validate that the user session is legitimate. This token is then passed to the component.

<head>
  <script src="https://cdn.cloud.corbado.io/connect/dist/web-js-latest.min.js"></script>
  <link rel="stylesheet" href="https://cdn.cloud.corbado.io/connect/dist/web-js-latest.min.css" />
  <script type="module">
    // This connect token must be generated on the server side
    // and passed to the component (e.g. by embedding it during server-side rendering).
    const connectToken = 'ctk-xxxxxxxxxxxxxxxxxxxxxxxxxx';

    const passkeyAppendElement = document.getElementById('passkey-append');
    Corbado.mountCorbadoConnectAppend(passkeyAppendElement, {
      projectId: "pro-9991871320976140999", // Your Corbado Project ID
      frontendApiUrlSuffix: "frontendapi.cloud.corbado.io", // Points to your chosen Corbado Frontend API environment

      // Called when the user decides not to create a passkey or passkey creation
      // is skipped. Add custom logic like logging and analytics.
      onSkip: (status) => { 
        console.log('Append skipped with status:', status);
      },

      // Provide the connect token to the component at runtime
      appendTokenProvider: async () => connectToken,

      // Called when passkey creation is completed successfully. Use to
      // refresh page or show success UI for example.
      onComplete: (status, clientState) => { 
        console.log('Append complete with status:', status);
      },
    });
  </script>
</head>

<body>
  <!-- The passkey append UI will render into this div -->
  <div id="passkey-append"></div>
</body>

​
Available Configuration Parameters

NameDescriptionRequiredType
onSkipCalled when the component skips rendering or the user actively dismisses it. The status string provides the reason, which can be gradual-rollout-denied (user not eligible), passkey-intelligence-denied (device not suitable), or user-skipped (user clicked skip).✅(status: string) => void
appendTokenProviderA function that is called after initial loading to retrieve the single-use ConnectToken needed to authorize passkey creation. This token must be generated on your backend.✅() => Promise<string>
onCompleteCalled when a passkey has been successfully appended. It provides the status (user-completed) and a clientState string, which should be stored client-side (e.g., in a cookie) to accelerate future passkey flows.✅(status: string, clientState: string) => void

​
Customization

You can customize the component’s appearance to match your application’s design in two ways:

​
1. Through CSS Theme Variables

The easiest way to change colors, fonts, and border-radius is by overriding our CSS theme variables. You can set these in a :root block in your stylesheet.

Variable NamePurpose/UseDefault Value
--cb-color-primaryPrimary colorrgb(79 91 146)
--cb-color-surface-tintSurface tint colorrgb(79 91 146)
--cb-color-on-primaryText color on primaryrgb(255 255 255)
--cb-color-primary-containerContainer color for primary elementsrgb(221 225 255)
--cb-color-on-primary-containerText color on primary containerrgb(7 22 75)
--cb-color-secondarySecondary colorrgb(90 93 114)
--cb-color-on-secondaryText color on secondaryrgb(255 255 255)
--cb-color-secondary-containerContainer color for secondary elementsrgb(223 225 249)
--cb-color-on-secondary-containerText color on secondary containerrgb(23 27 44)
--cb-color-errorError message colorrgb(186 26 26)
--cb-color-on-errorText color on errorrgb(255 255 255)
--cb-color-error-containerContainer color for error elementsrgb(255 218 214)
--cb-color-on-error-containerText color on error containerrgb(65 0 2)
--cb-color-backgroundBackground colorrgb(251 248 255)
--cb-color-on-backgroundText color on backgroundrgb(27 27 33)
--cb-color-surfaceSurface colorrgb(251 248 255)
--cb-color-on-surfaceText color on surfacergb(27 27 33)
--cb-color-surface-variantVariant surface colorrgb(226 225 236)
--cb-color-on-surface-variantText color on surface variantrgb(69 70 79)
--cb-color-outlineOutline colorrgb(118 118 128)
--cb-font-family-primaryPrimary font family’Space Grotesk’, sans-serif
--cb-border-radiusBorder radius for elements0rem

​
2. Through CSS Classes

For more detailed changes, you can directly target the component’s CSS classes. All classes are scoped under the .cb-connect-container to avoid conflicts.

​
Shared CSS Classes

These classes are used across multiple Corbado Connect components.

Class NameUsage
.cb-h2Used for heading level 2 styling
.cb-pUsed for paragraph text styling
.cb-boldUsed for bold text
.cb-link-buttonUsed for link-style buttons
.cb-connect-containerThe top-level container for the component
.cb-primary-buttonUsed for primary buttons
.cb-secondary-buttonUsed for secondary buttons
.cb-notification-containerUsed for notification containers
.loaderUsed for loader/spinner animations

​
Component Specific CSS Classes

These classes are specific to the CorbadoConnectAppend component.

Class NameUsage
.cb-passkey-info-list-itemStyles for items in the passkey info list
.cb-append-benefits-iconsContainer for displaying benefit icons
.cb-append-info-listStyles for the append information list
.cb-append-headerStyles for the header section
.cb-append-benefits-containerContainer for organizing append benefits
.cb-connect-append-ctaStyles for call-to-action elements container
.cb-append-buttonStyles for append buttons
.cb-append-iconStyles for icons in append features
.cb-append-skipStyles for the skip option
.cb-append-skip-containerContainer for skip option elements

​
Next steps: Get in touch

Corbado Connect is currently not offered as self-service option. For inquiries, demonstrations, or to discuss enterprise deployment options, please contact us:

We look forward to helping you deploy passkeys seamlessly—while protecting your existing investments and infrastructure.