​
Introduction

Enterprise passkey integrations can be complex especially when you have multiple systems, existing authentication flows, and varied compliance requirements. Corbado Connect aims to simplify this by providing JavaScript-based UI components that work seamlessly in any front-end environment. These components handle the heavy lifting of passkey ceremonies, fallback logic, and user interactions, letting you focus on building great user experiences.

Corbado’s approach is lightweight: you embed our JavaScript library or use npm packages to mount passkey related components in your code. This guide shows a short introduction to the two core components CorbadoConnectAppend and CorbadoConnectLogin and also briefly introduces CorbadoConnectPasskeyList for passkey management.

This article focuses primarily on the automatic login approach tailored for identifier-first implementations. If you’re interested in learning more about implementing passkeys using our passkey button approach with Corbado’s UI components, feel free to contact us directly for further details.

​
1. Components as one part of the Enterprise Passkey Platform

Frontend Components are only one part of the integration options provided by Corbado. In addition to their primary passkey functionality, all components also collect Passkey Intelligence and Tracking Signals. This allows for optimized decision-making and enhances the overall security and user experience.

​
2. Configuration Supported by All Components

Each Corbado Connect UI component supports a common set of configuration parameters:

NameDescriptionRequiredType
projectIdThe ID of the Corbado project. See the integration guide for an explanation of how to handle situations where multiple project IDs are needed.✅string
frontendApiUrlSuffixThe Corbado Frontend API to connect to. You can specify whether the component connects to the staging or production environment.✅string
isDebugIf set to true, the Corbado Connect UI components will log debug information to the console. Useful for development, but should be disabled in production.boolean
enableHighlightIf set to true, components are visually surrounded by a red box—helpful in development to understand the scope of each component in your layout.boolean
flagsAn object that defines default flags to include in requests to Corbado’s Frontend API. Currently, only "conditional-ui-allowed" is used; more flags may be added in the future as needed.object

​
2. CorbadoConnectAppend

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.

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

​
2.1 Example

<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 connectAppendToken = 'ctk-xxxxxxxxxxxxxxxxxxxxxxxxxx';

    const passkeyAppendElement = document.getElementById('passkey-append');
    Corbado.mountCorbadoConnectAppend(passkeyAppendElement, {
      projectId: "pro-9991871320976140999", // Your project's Corbado 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
      onSkip: (status) => { /* custom logic, e.g., logging or analytics */ },

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

      // Called when passkey creation is completed successfully
      onComplete: (status, clientState) => { /* e.g., refresh page, show success UI, etc. */ },
    });
  </script>
</head>

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

​
2.2 Available Configuration Parameters

NameDescriptionRequiredType
onSkipThis function is called when the component skips the passkey append process. This happens for the following reasons: Gradual rollout does not allow the append Passkey intelligence does not allow the append The user actively skips the append✅(appendStatus: AppendStatus) => void
appendTokenProviderThis function is called right after the component has finished its initial loading to retrieve an appendToken.✅() => Future<string>
onCompleteThis function is called when a passkey has been successfully appended to the user’s account. It provides both the appendStatus and a clientState string, which can be stored on the client side (e.g., a cookie) to accelerate future passkey flows.✅(appendStatus: AppendStatus, clientState: string) => void

​
3. CorbadoConnectLogin

CorbadoConnectLogin handles passkey logins. You might embed this component in a modal or on a dedicated login page. It’s responsible for prompting the user to log in with a passkey and managing fallback if no passkey is available or if the passkey flow fails.

​
3.1 Example

<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">
    const passkeyLoginElement = document.getElementById('authorize-with-passkey');
    Corbado.mountCorbadoConnectLogin(passkeyLoginElement, {
      projectId: "pro-9991871320976140999",
      frontendApiUrlSuffix: "frontendapi.cloud.corbado.io",

      // Called when passkey login is completed successfully
      onComplete: (signedPasskeyData, clientState) => {
        fetch(SYSTEM_BE_URL, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({ signedPasskeyData: signedPasskeyData, clientState: clientState }),
        }).then(() => {
          // e.g., update the embedding application state to proceed with the next step
        });
      },

      // Called when passkey login is not possible or fails
      onFallback: (identifier, errorMessage) => {
        // e.g., show a fallback UI (password, OTP, etc.)
      },
    });
  </script>
</head>

<body>
  <div id="authorize-with-passkey"></div>
  <div id="authorize-with-fallback">
    <!-- Fallback UI logic here (Your existing fallback authentication comes here) -->
  </div>
</body>

​
3.2 Available Configuration Parameters

NameDescriptionRequiredType
onCompleteInvoked upon a successful passkey login. Receives signedPasskeyData (a signed JWT containing cryptographic proof of a successful passkey ceremony) and clientState (an encoded string to speed up future passkey operations). Store clientState as a cookie or localStorage for a smoother user experience later.✅(signedPasskeyData: string, clientState: string) => void
onFallbackCalled if passkey login isn’t possible (e.g., no passkey available) or fails unexpectedly. Provides an identifier (such as an email address the user entered) and an errorMessage you can display. Typically, you’d redirect or display a fallback authentication method (password, SMS OTP, etc.).✅(identifier: string, errorMessage: string) => void

​
4. CorbadoConnectPasskeyList

CorbadoConnectPasskeyList provides a user interface for users to view and manage their passkeys:

  • Listing Passkeys: Displays passkeys linked to the user’s account.
  • Deleting Passkeys: Allows users to remove unneeded or compromised passkeys.
  • Passkey Creation: Users can also add more passkeys from within this interface.

Note: The implementation details for mounting callbacks and events align with those of CorbadoConnectAppend and CorbadoConnectLogin.

​
5. ConnectTokens (CTK)

ConnectTokens were mentioned in the documentation for the CorbadoConnectAppend component:

“For passkey creation, you must generate a secure ConnectToken on your backend to validate that the user session is legitimate. This token is then passed to the component.”

Below is a detailed explanation of how ConnectTokens are generated and why they are necessary.

A Corbado ConnectToken (CTK) is a short-lived, single-use token that securely ties user context (e.g., which account is being updated) to a particular Corbado Connect UI component action (such as passkey creation, passkey listing, or passkey deletion).

Whenever a front-end flow (like Append a Passkey or Delete a Passkey) needs to safely reference a specific user’s account, a CTK is required. These tokens are created on the server side (server-to-server via the Corbado Backend API) and then passed to the relevant front-end component.

  1. Server generates a CTK
    Your server (e.g., “Customer Backend”) makes a secure API call to Corbado’s POST /v2/connectTokens endpoint. This endpoint identifies the user (for example, through a CustomerIdentifier) and specifies the intended action ("passkey-append", "passkey-list", "passkey-delete", etc.).
  2. Token includes user-specific data
    The response from Corbado includes a unique ConnectToken (e.g., ctk-123...). This token tells the Corbado Connect UI component precisely which user and which action it is authorized to perform (e.g., “create a new passkey for user 123”).
  3. Frontend (UI component) consumes the CTK
    On the frontend, a Corbado Connect UI component (such as CorbadoConnectAppend) receives the token, validates it, and initiates the passkey flow. During the process, Corbado checks the token’s validity (expiration time, intended user, single use, etc.).
  4. Single use & short-lived
    Each CTK is valid for one passkey change operation (e.g., a single passkey creation) and expires after a short period of time (configurable in Corbado’s systems). Once used or expired, it can’t be reused. This design helps prevent replay attacks or unauthorized reuse.

Note:
Login flows (CorbadoConnectLogin) do not require CTKs. However, other passkey flows that change data related to a user’s account (such as appending a new passkey or deleting an existing one) must be bound to the user’s session by using a ConnectToken.

In summary, every time a passkey change flow runs (like passkey creation or passkey deletion), your backend will need to:

  1. Verify the user is authenticated (or authorized) to update their passkeys.
  2. Generate a CTK via the Corbado Backend API for the specific user and action.
  3. Deliver the CTK to the frontend (e.g., embed it in your response or SSR).
  4. Consume the CTK in the relevant Corbado Connect UI component, ensuring a secure, single-use passkey change operation.

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

Was this page helpful?

Suggest edits