Pelican Identity React SDK

React SDK for Pelican authentication and identity verification on the web. 👉 Pelican Dashboard: https://dash.pelicanidentity.com

Installation

Using npm

npm install @pelican-identity/react

Using yarn

yarn add @pelican-identity/react

Using pnpm

pnpm add @pelican-identity/react

Requirements

• React 17, 18, or 19
• A modern browser environment
• A Pelican project configured in the Pelican dashboard

This SDK is browser-only and must be used in client-side React components.

Required Setup

1. Whitelist your domain in Pelican Dashboard

You must add your website’s domain (e.g. example.com, app.example.com, or localhost) to your project’s whitelist in the Pelican dashboard.

Pelican validates explicit domain ownership on every authentication attempt. 👉 Pelican Dashboard: https://dash.pelicanidentity.com

2. Client-side usage only (important)

If you are using Next.js, Remix, or similar frameworks, ensure the SDK is only initialized on the client.

For Next.js App Router:

"use client";

Usage

Basic Usage

import { PelicanAuth } from "@pelican-identity/react";

export default function LoginPage() {
  return (
    <PelicanAuth
      publicKey="your-business-public-key"
      projectId="your-project-id"
      authType="login"
      onSuccess={(data) => {
        console.log("Authentication successful:", data);
      }}
      onError={(error) => {
        console.error("Authentication failed:", error);
      }}
    />
  );
}

Complete Example

"use client";

import { useState } from "react";
import { PelicanAuth } from "@pelican-identity/react";

export default function Login() {
  const [user, setUser] = useState(null);
  const [error, setError] = useState<string | null>(null);

  return (
    <div style={{ maxWidth: 400, margin: "auto" }}>
      <h2>Login to MyApp</h2>

      <PelicanAuth
        publicKey="your-business-public-key"
        projectId="your-project-id"
        authType="login"
        onSuccess={(data) => {
          setUser(data);
          setError(null);
        }}
        onError={(err) => {
          setError(err.message);
          setUser(null);
        }}
      />

      {user && <p>Authenticated successfully</p>}
      {error && <p style={{ color: "red" }}>{error}</p>}
    </div>
  );
}

API Reference

PelicanAuth

Main authentication component.

Props

| Prop | Type | Required | Description | | ----------------- | ------------------------------------------ | -------- | --------------------------------------------------- | | publicKey | string | ✅ | Business public key from Pelican dashboard | | projectId | string | ✅ | Project ID from Pelican dashboard | | authType | "signup" \| "login" \| "id-verification" | ✅ | Authentication flow | | onSuccess | (data: IdentityResult) => void | ✅ | Success callback containing authenticated user data | | onError | (error: Error) => void | Optional | Error callback | | buttonComponent | ReactNode | Optional | Custom trigger UI | | forceQRCode | boolean | Optional | Always show QR code instead of deep link | | continuousMode | boolean | Optional | Automatically restart auth after completion |

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

Blank page or no QR code

• Ensure the SDK is running client-side
• Confirm your domain is whitelisted

Authentication never completes

• Ensure the browser tab regains focus after mobile authentication

Unsupported authentication type

• Ensure authType is valid

Billing issues, please contact this site owner

• Ensure your business wallet has sufficient balance
• Low balance alerts can be configured in the Pelican dashboard 👉 Pelican Dashboard: https://dash.pelicanidentity.com

Security Notes

• All identity data is transmitted encrypted.
• Pelican never exposes raw credentials.
• Identifiers are scoped per business.
• Domains are validated on every authentication request.

Final note

Pelican deliberately separates:

• Identity (who the user is)
• Authentication (this session)
• Verification (confidence level)

This ensures your web application remains secure, flexible, and compliant.

License

MIT