npm package: @pelican-identity/react
Description: React components for Pelican Identity authentication
Latest version: 2.0.50

# Pelican Identity React SDK

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

---

## Installation

### Using npm

```bash
npm install @pelican-identity/react
```

### Using yarn

```bash
yarn add @pelican-identity/react
```

### Using pnpm

```bash
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:

```tsx
"use client";
```

---

## Usage

### Basic Usage

```tsx
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

```tsx
"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

```ts
onSuccess: (result: IdentityResult) => void;
```

---

## IdentityResult

```ts
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;
  };
  /** Location data from the user's device */
  location?: { latitude: number; longitude: number } | null;
}
```

---

## `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.

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

## User Data (`user_data`)

Returned when available and permitted by the authentication flow.

```ts
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

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

### Phone

```ts
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.

```ts
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:

```ts
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