This documentation provides a comprehensive guide for using the Pelican Identity Vanilla SDK. It covers three integration paths: using the pre-built UI via CDN, using the UI wrapper via NPM, and building a custom UI using the Core Engine.

Pelican Identity Vanilla SDK

The Vanilla SDK provides a framework-agnostic way to integrate Pelican authentication. It includes a high-level UI wrapper that mirrors the React experience and a low-level Core Engine for custom implementations.

Installation

1. Via CDN (Easiest)

Ideal for projects without a build step. Includes the UI and logic in a single file.

<script src="https://cdn.jsdelivr.net/npm/@pelican-identity/[email protected]/dist/index.min.js"></script>

<div id="pelican-auth-root"></div>

<script>
  const auth = Pelican.createPelicanAuth("pelican-auth-root", {
    publicKey: "your-business-public-key",
    projectId: "your-project-id",
    authType: "login",
    onSuccess: (data) => console.log("Success:", data),
    onError: (err) => console.error("Error:", err),
  });
</script>

2. Via NPM/PNPM

Ideal for modern web apps (Vue, Svelte, or Vanilla TS) using a bundler like Vite or Webpack.

npm install @pelican-identity/vanilla

import { createPelicanAuth } from "@pelican-identity/vanilla";

const cleanup = createPelicanAuth("container-id", {
  publicKey: "...",
  projectId: "...",
  authType: "login",
  onSuccess: (identity) => {
    console.log(identity.user_id);
  },
});

// To stop and cleanup the instance
// cleanup();

UI Wrapper API Reference (createPelicanAuth)

The createPelicanAuth function initializes the Pelican UI inside a target DOM element.

| Option | Type | Required | Description | | ---------------- | ---------- | -------- | --------------------------------------------- | | publicKey | string | ✅ | Business public key from Pelican dashboard | | projectId | string | ✅ | Project ID from Pelican dashboard | | authType | AuthType | ✅ | "signup", "login", or "id-verification" | | onSuccess | Function | ✅ | Callback with IdentityResult | | onError | Function | ❌ | Callback for errors | | onClose | Function | ❌ | Callback when the user closes the modal | | continuousMode | boolean | ❌ | Auto-restart auth after completion | | forceQRCode | boolean | ❌ | Always show QR even on mobile | | buttonText | string | ❌ | Custom text for the Pelican button |

Low-Level Core Usage (Custom UI)

If you want to build your own UI from scratch, use the @pelican-identity/auth-core package directly. This provides the event-driven state machine without any HTML/CSS.

Basic Implementation

import { PelicanAuthentication } from "@pelican-identity/auth-core";

const pelican = new PelicanAuthentication({
  publicKey: "your-key",
  projectId: "your-id",
  authType: "login",
});

// 1. Listen for the QR code
pelican.on("qr", (qrDataUrl) => {
  document.getElementById("my-qr").src = qrDataUrl;
});

// 2. Listen for Mobile Deep Links
pelican.on("deeplink", (url) => {
  document.getElementById("mobile-link").href = url;
});

// 3. Track State Changes
pelican.on("state", (state) => {
  console.log("Current state:", state); // 'initializing', 'paired', etc.
});

// 4. Handle Completion
pelican.on("success", (identity) => {
  alert(`Welcome ${identity.user_id}`);
});

// Start the engine
pelican.start();

Authentication Flow logic

The SDK manages the transition between Desktop and Mobile automatically:

1. Desktop: Emits a qr event containing a Base64 Data URL.
2. Mobile: Emits a deeplink event. Browsers should provide a "Open App" button using this URL.
3. Paired: Once the user scans/clicks, the state moves to paired.
4. Success: After biometric/PIN approval in the Pelican app, the success event fires with user data.

Identity Result Structure

Regardless of which integration path you choose, the successful authentication returns this object:

interface IdentityResult {
  user_id: string; // Unique business-scoped identifier
  user_data?: {
    first_name?: string;
    email?: { value: string; verified: boolean };
    phone?: { number: string; verified: boolean };
  };
  id_verification?: {
    status: "Approved" | "Declined";
    document_type: string;
  };
}

Troubleshooting

crypto.randomUUID is not a function

Cause: Browsers only allow the Crypto API in Secure Contexts (HTTPS or localhost). Fix: Ensure you are serving your site over HTTPS or using http://localhost.

QR Code not showing

Cause: The engine might be in initializing state or the domain isn't whitelisted. Fix: Check your Pelican Dashboard and ensure your current domain (including port if applicable) is added to the project whitelist.

Would you like me to help you create a "Getting Started" guide specifically for the Pelican Dashboard setup to complement this SDK documentation?