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 | | forceQRCode | boolean (default: false) | Optional | Always show QR code instead of deep link | | continuousMode | boolean (default: false) | Optional | Automatically restart auth after completion | | disableWebAuth | boolean (default: false) | Optional | Disable web authentication, useful for phyiscal access control and kiosks |

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;
  };
  /** JWT Token signed token */
  token?: string;
}

token

• A JWT (JSON Web Token) issued by Pelican after a successful user authentication or action approval.
• This token represents a verified user interaction and can be used to confirm identity and/or intent on your backend.

Verification

To verify a Pelican token, your backend must send it to the Pelican Identity API.

Endpoint

POST https://identityapi.pelicanidentity.com/verify-session

Headers

Include the following headers in your request:

• x-public-key — Your Pelican public API key

Request Body

{
  "token": "YOUR_PELICAN_JWT_TOKEN"
}

Example (Node.js)

const response = await fetch(
  "https://identityapi.pelicanidentity.com/verify-session",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-public-key": process.env.PELICAN_PUBLIC_KEY,
    },
    body: JSON.stringify({
      token: pelicanToken,
    }),
  },
);

const data = await response.json();

Response

A successful response will return a verified payload containing:

• pelican_id — Pelican user identity details
• verified — Boolean indicating token validity
• issued_at — Timestamp of when the token was generated
• expires_at — Token expiration timestamp

Example Response

{
  "verified": true,
  "pelican_id": "4dbde492db8f64aff80b1dd61754a84bdf2dc87eed1b19fec4cd66569856b134",
  "issued_at": 1714483200,
  "expires_at": 1714483500
}

Notes

• Always verify the token on your backend before trusting any user action.
• Tokens are short-lived and should not be reused.
• Never trust tokens directly from the client without verification.

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?