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();

<script>
  import { onMount } from 'svelte';

  onMount(() => {
    // Pelican is available globally because of the CDN <script> tag
    const auth = window.Pelican.createPelicanAuth('pelican-container', {
      publicKey: "your-key",
      projectId: "your-id",
      authType: "login",
      onSuccess: (data) => console.log(data)
    });

    // Cleanup when component is destroyed
    return () => auth();
  });
</script>

<div id="pelican-container"></div>

<template>
  <div id="pelican-container"></div>
</template>

<script setup>
import { onMounted } from "vue";

onMounted(() => {
  const auth = window.Pelican.createPelicanAuth("pelican-container", {
    publicKey: "your-key",
    projectId: "your-id",
    authType: "login",
    onSuccess: (data) => console.log(data),
  });

  return () => auth();
});
</script>

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.

If appId is missing or does not match the whitelisted value, Pelican will fail immediately.

Best practice

Fetch your Pelican configuration (public key, project ID) from your backend at runtime instead of hard-coding them into your mobile app. 👉 Pelican Dashboard: https://dash.pelicanidentity.com

Authentication Response

When authentication completes successfully, Pelican returns a structured identity result to your application via the onSuccess callback.

This response contains a deterministic user identifier for your business, along with optional verified user data and identity verification (KYC) information depending on the authentication flow used.

Success Callback

onSuccess: (result: IdentityResult) => void;

IdentityResult

interface IdentityResult {
  /** Deterministic unique user identifier specific to your business */
  user_id: string;

  /** Authentication Assurance level */
  /** AAL1 - Passcode */
  /** AAL2 - Biometric */
  assurance_level: { level: number; type: "passcode" | "biometric" };
  /** Basic user profile and contact information (if available) */
  user_data?: IUserData;

  /** Identity document and liveness verification data */
  id_verification: IKycData;

  /** Download URLs for verified identity documents */
  id_downloadurls?: {
    front_of_card?: string;
    back_of_card?: string;
  };
}

user_id

• A stable, deterministic identifier generated by Pelican.
• Unique per business, not global.
• Safe to store and use as your internal user reference.
• Does not expose personally identifiable information (PII).

This identifier remains the same for the same user across future authentications within your business.

Assurance Level (assurance_level)

Pelican will prompt users to authenticate using the required assurance level configured in the project settings when possible. Authentication may still succeed with a lower level, but the achieved assurance level is always returned in the response. Your application is responsible for enforcing access based on this level.

interface AssuranceLevel {
  level: number;
  type: "passcode" | "biometric";
}

User Data (user_data)

Returned when available and permitted by the authentication flow.

interface IUserData {
  first_name?: string;
  last_name?: string;
  other_names?: string;
  email?: IEmail;
  phone?: IPhone;
  dob?: string | Date;
  gender?: "male" | "female" | "other";
  country?: string;
  state?: string;
  city?: string;
  address?: string;
  occupation?: string;
  company?: string;
  website?: string;
}

Email

interface IEmail {
  id: number;
  value: string;
  verifiedAt: string;
  verificationProvider: string;
}

Phone

interface IPhone {
  id: number;
  country: string;
  callingCode: string;
  number: string;
  verifiedAt: string;
  verificationProvider: string;
}

All contact data returned by Pelican is verified and includes the service used for verification.

Identity Verification (id_verification)

Returned for flows involving identity verification or KYC.

interface IKycData {
  id: number;
  status?: "Approved" | "Declined" | "In Review";
  document_type?:
    | "national id card"
    | "passport"
    | "driver's license"
    | "residence permit";
  document_number?: string;
  personal_number?: string;
  date_of_birth?: string | Date;
  age?: number;
  expiration_date?: string | Date;
  date_of_issue?: string | Date;
  issuing_state?: string;
  issuing_state_name?: string;
  first_name?: string;
  last_name?: string;
  full_name?: string;
  gender?: string;
  address?: string;
  formatted_address?: string;
  nationality?: string;
  liveness_percentage?: number;
  face_match_percentage?: number;
  verified_at?: string | Date;
}

Verification Scores

• liveness_percentage: Confidence score (0–100) from face liveness detection.
• face_match_percentage: Confidence score (0–100) matching selfie to document photo.

Document Downloads

If document access is enabled for your project (NB: your business must be verified and KYB completed), Pelican provides secure download URLs valid for 24 hours as Pelican does not store documents and only provides access to them from the Pelican vault for a limited time. You are required to download and store the documents on your backend for compliance and security reasons according to your local data protection regulations:

id_downloadurls?: {
  front_of_card?: string;
  back_of_card?: string;
};

These URLs are:

• Short-lived
• Access-controlled
• Intended for secure backend or compliance workflows

Authentication Flow Differences

| Auth Type | Returned Data | | ----------------- | ------------------------------------------- | | signup | user_id, basic user_data | | login | user_id, previously generated at signup | | id-verification | user_id, id_verification, document URLs |

Returned fields depend on:

• User consent
• Project configuration
• Regulatory requirements

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.