Quick Start

This guide will help you get started with the FaceSign API. You'll learn how to create your first verification session and integrate identity verification into your application.

Get your API keys

First, you'll need to get your API keys from the FaceSign dashboard.

1. Log in to your FaceSign dashboard
2. Navigate to Settings → API Keys
3. Copy your API key (starts with sk_test_ for test mode or sk_live_ for production)

Install the SDK

Choose your preferred language and install the FaceSign SDK:

npm install @facesign/sdk

Create your first session

Now let's create a verification session. Sessions are the core of FaceSign - they represent a single identity verification flow.

import { FaceSign } from '@facesign/sdk';

const facesign = new FaceSign({
  apiKey: process.env.FACESIGN_API_KEY,
});

const session = await facesign.sessions.create({
  mode: 'redirect',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  metadata: {
    user_id: '123456',
  },
});

console.log(session.url); // Redirect your user to this URL

Redirect your user

After creating a session, you'll receive a response with a url field. Redirect your user to this URL to start the verification process:

{
  "id": "vs_1a2b3c4d5e6f",
  "object": "verification_session",
  "client_secret": "vs_1a2b3c4d5e6f_secret_abc123",
  "url": "https://verify.facesign.ai/s/vs_1a2b3c4d5e6f",
  "status": "pending",
  "mode": "redirect",
  "success_url": "https://example.com/success",
  "cancel_url": "https://example.com/cancel",
  "metadata": {
    "user_id": "123456"
  },
  "created": 1234567890,
  "expires": 1234571490
}

Handle the result

After the user completes or cancels the verification, they'll be redirected to your success_url or cancel_url with the session ID as a query parameter:

https://example.com/success?session_id=vs_1a2b3c4d5e6f

You can then retrieve the session to check the verification status:

const session = await facesign.sessions.retrieve('vs_1a2b3c4d5e6f');

if (session.status === 'verified') {
  // User successfully verified their identity
  console.log('Verification successful!');
  console.log('Verified data:', session.verified_outputs);
} else if (session.status === 'failed') {
  // Verification failed
  console.log('Verification failed');
}

What's next?

Congratulations! You've created your first verification session. Here are some next steps: