CorbadoConnectAppend: Add Passkeys to Accounts

Try Demo

Talk to Adoption Engineer

Whitepaper

1. Introduction

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. CorbadoConnectAppend Component

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

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

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.
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. In web environments, it can also detect many password managers and skip the offer if a detected manager is excluded by your Authenticator Policy. This avoids showing the passkey enrollment screen and a likely decline after creation; onSkip receives skip-implicit.
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.
Passkey Creation: Once the user agrees, the component initiates the WebAuthn API. The selected provider creates and may save the passkey locally.
Enrollment Acceptance: Corbado validates the registration and evaluates any configured Authenticator Policy before accepting the credential for future login. An accepted enrollment reaches the success screen. A policy decline opens the supported-alternatives screen described below.

4. 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:

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

5. Errors and Enrollment Declines

If a technical issue occurs during passkey creation or the user closes the browser prompt, the component explains the result and offers a retry where appropriate. An enrollment declined by policy has a separate recovery path.

5.1 Enrollment declined by policy

When the returned credential does not meet your Authenticator Policy, the component explains that it has not been added to the account and offers supported providers. For example:

Choose another passkey provider This provider does not meet the passkey requirements for your account. Create a passkey with one of the supported providers below. Your current sign-in remains active.

The user can choose to try again with a supported provider or continue without adding a passkey. The component supplies guidance for choosing another provider in the browser or operating-system prompt; it cannot silently change the user’s default manager. Continuing preserves the existing application session. The declined credential is not accepted for future login. It may still exist in the credential manager, which can offer it at a later login. The component provides instructions to remove that entry and uses cleanup signals where supported. Provider support varies, so automatic removal is not guaranteed.

5.2 Integration outcomes

Treat local creation and accepted enrollment as separate events:

Accepted enrollment: onComplete reports successful completion. Show your success UI only after the component confirms the result.
Policy decline: The component keeps the user in the enrollment flow and reports a diagnostic code through onError. It does not call onComplete for the declined credential. Track the policy outcome separately from technical errors.
Retry: The component starts another attempt after the user chooses to retry. A later accepted attempt can complete normally.
Continue without enrollment: onSkip lets your application continue its authenticated journey when the user dismisses the offer, including after a decline.

A decline is a decision about the new credential. It does not revoke another passkey or invalidate the user’s existing session.

6. Example

Important: Only authenticated users are allowed to create new passkeys. You must generate a connect token 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 = 'ctk1_xxx';

    const passkeyAppendElement = document.getElementById('passkey-append');
    Corbado.mountCorbadoConnectAppend(passkeyAppendElement, {
      projectId: "pro-XXX", // 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: async (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: async (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>

7. Available Configuration Parameters

The callback types below describe the SDK integration contract. See the Web SDK for installation.

Name	Description	Required	Type
`onSkip`	Called with `skip-implicit` when enrollment is skipped by the flow, or `skip-explicit` when the user dismisses it. Continue your application journey in either case.	Yes	`(status: AppendStatus) => Promise<void>`
`appendTokenProvider`	Fetches a fresh, action-specific Connect token from your authenticated backend.	Yes	`() => Promise<string>`
`onComplete`	Receives `complete` after enrollment, or `complete-noop` when the authenticator reports an existing credential. The second argument contains client state.	Yes	`(status: AppendStatus, clientState: string) => Promise<void>`
`situation`	Identifies the authenticated enrollment context for configured rules, for example `post-login`. Agree on other values with Corbado.	No	`string`
`onError`	Receives a diagnostic code for a technical error or policy decline. The component handles the decline screen and retry. Use the code for diagnostics without treating it as proof that the user enrolled.	No	`(error: string) => void`

AppendStatus is the union skip-implicit, skip-explicit, complete and complete-noop. Keep skips and no-op completions separate from new credential creation in your own analytics.

8. Customization

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

8.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 Name	Purpose/Use	Default Value
`--cb-color-primary`	Primary color	rgb(79 91 146)
`--cb-color-surface-tint`	Surface tint color	rgb(79 91 146)
`--cb-color-on-primary`	Text color on primary	rgb(255 255 255)
`--cb-color-primary-container`	Container color for primary elements	rgb(221 225 255)
`--cb-color-on-primary-container`	Text color on primary container	rgb(7 22 75)
`--cb-color-secondary`	Secondary color	rgb(90 93 114)
`--cb-color-on-secondary`	Text color on secondary	rgb(255 255 255)
`--cb-color-secondary-container`	Container color for secondary elements	rgb(223 225 249)
`--cb-color-on-secondary-container`	Text color on secondary container	rgb(23 27 44)
`--cb-color-error`	Error message color	rgb(186 26 26)
`--cb-color-on-error`	Text color on error	rgb(255 255 255)
`--cb-color-error-container`	Container color for error elements	rgb(255 218 214)
`--cb-color-on-error-container`	Text color on error container	rgb(65 0 2)
`--cb-color-background`	Background color	rgb(251 248 255)
`--cb-color-on-background`	Text color on background	rgb(27 27 33)
`--cb-color-surface`	Surface color	rgb(251 248 255)
`--cb-color-on-surface`	Text color on surface	rgb(27 27 33)
`--cb-color-surface-variant`	Variant surface color	rgb(226 225 236)
`--cb-color-on-surface-variant`	Text color on surface variant	rgb(69 70 79)
`--cb-color-outline`	Outline color	rgb(118 118 128)
`--cb-font-family-primary`	Primary font family	’Space Grotesk’, sans-serif
`--cb-border-radius`	Border radius for elements	0rem

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

8.2.1 Shared CSS Classes

These classes are used across multiple Corbado Connect components.

Class Name	Usage
`.cb-h2`	Used for heading level 2 styling
`.cb-p`	Used for paragraph text styling
`.cb-bold`	Used for bold text
`.cb-link-button`	Used for link-style buttons
`.cb-connect-container`	The top-level container for the component
`.cb-primary-button`	Used for primary buttons
`.cb-secondary-button`	Used for secondary buttons
`.cb-notification-container`	Used for notification containers
`.loader`	Used for loader/spinner animations

8.2.2 Component Specific CSS Classes

These classes are specific to the CorbadoConnectAppend component.

Class Name	Usage
`.cb-passkey-info-list-item`	Styles for items in the passkey info list
`.cb-append-benefits-icons`	Container for displaying benefit icons
`.cb-append-info-list`	Styles for the append information list
`.cb-append-header`	Styles for the header section
`.cb-append-benefits-container`	Container for organizing append benefits
`.cb-connect-append-cta`	Styles for call-to-action elements container
`.cb-append-button`	Styles for append buttons
`.cb-append-icon`	Styles for icons in append features
`.cb-append-skip`	Styles for the skip option
`.cb-append-skip-container`	Container for skip option elements

Overview

Flows

Architecture

Web UI Components

Management Console

Integration

Features

Concepts

Helpful Guides

Security & Compliance

CorbadoConnectAppend: Add Passkeys to Accounts

1. Introduction

2. When to Use This Component

3. Rendering Logic

4. User Experience

5. Errors and Enrollment Declines

5.1 Enrollment declined by policy

5.2 Integration outcomes

6. Example

7. Available Configuration Parameters

8. Customization

8.1 Through CSS Theme Variables

8.2 Through CSS Classes

8.2.1 Shared CSS Classes

8.2.2 Component Specific CSS Classes

​1. Introduction

​2. When to Use This Component

​3. Rendering Logic

​4. User Experience

​5. Errors and Enrollment Declines

​5.1 Enrollment declined by policy

​5.2 Integration outcomes

​6. Example

​7. Available Configuration Parameters

​8. Customization

​8.1 Through CSS Theme Variables

​8.2 Through CSS Classes

​8.2.1 Shared CSS Classes

​8.2.2 Component Specific CSS Classes

1. Introduction

2. When to Use This Component

3. Rendering Logic

4. User Experience

5. Errors and Enrollment Declines

5.1 Enrollment declined by policy

5.2 Integration outcomes

6. Example

7. Available Configuration Parameters

8. Customization

8.1 Through CSS Theme Variables

8.2 Through CSS Classes

8.2.1 Shared CSS Classes

8.2.2 Component Specific CSS Classes