Skip to main content

Quick Start

Get face verification running in your application in under 5 minutes.

1
Get Credentials
API key from your dashboard
2
Generate Token
Server-side API call
3
Embed FaceGuard
Drop in the SDK or iframe

1. Get Your Credentials​

After Surt provides you with login credentials:

  • An API key is created for your organization
  • Create a workflow in your dashboard to get a workflow_id

Your API key goes in the Authorization header of every backend request. Never expose it in client-side code. See Authentication for details.

2. Generate a Portal Token​

Call the Surt API from your backend to create a portal token:

cURL
curl --location 'https://api.surt.com/faceguard/session/portal' \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
    "workflow_id": "YOUR_WORKFLOW_ID",
    "customer": {
        "customer_id": "your_user_id",
        "email": "user@example.com",
        "first_name": "John",
        "last_name": "Doe"
    }
}'

The response contains a JWT portal token. Pass this token to your frontend.

Portal token expiry

Portal tokens expire after 30 minutes. Generate a fresh token for each verification attempt.

3. Embed FaceGuard​

npm install @surtai/faceguard
TypeScript
import { FaceGuard } from '@surtai/faceguard';

const result = await FaceGuard.verify({ token: 'YOUR_PORTAL_TOKEN' });

if (result.status === 'approved') {
  // Grant access
} else if (result.status === 'rejected') {
  // Deny access or retry with a new token
}

The SDK auto-detects the device: fullscreen camera on mobile, QR code modal on desktop.

Option B: iframe​

HTML
<div
  id="faceguard-container"
  style="position: fixed; inset: 0; z-index: 9999; background: #0D141A;"
>
  <iframe
    src="https://faceguard.surt.com/intro?token=YOUR_PORTAL_TOKEN"
    allow="camera"
    style="width: 100%; height: 100%; border: none;"
  ></iframe>
</div>

Option C: React Native​

npm install @surtai/faceguard-rn react-native-webview
React Native
import { FaceGuard, FaceGuardProvider } from '@surtai/faceguard-rn';

// Wrap your app root with FaceGuardProvider, then:
const result = await FaceGuard.verify({ token: 'YOUR_PORTAL_TOKEN' });

if (result.status === 'approved') {
  // Grant access
} else if (result.status === 'rejected') {
  // Deny access or retry with a new token
}

4. Handle the Result​

SDK callbacks​

TypeScript
const fg = FaceGuard.init({
  token: 'YOUR_PORTAL_TOKEN',
  onSuccess: (result) => console.log('Approved', result.confidence),
  onFailed: (result) => console.log('Rejected', result.confidence),
  onCancel: () => console.log('User canceled'),
  onError: (error) => console.log('Error', error.message),
});

postMessage events (iframe)​

JavaScript
window.addEventListener('message', (e) => {
  if (e.origin !== 'https://faceguard.surt.com') return;

  if (e.data?.action === 'close') {
    switch (e.data.reason) {
      case 'approved':   // Face verified - confidence: 0-100
      case 'rejected':   // Face did not match - confidence: 0-100
      case 'canceled':   // User closed FaceGuard
      case 'error':      // Something went wrong - error message
    }
    document.getElementById('faceguard-container')?.remove();
  }
});
tip

Use sandbox mode during development. Contact Surt to get sandbox credentials.

Next Steps​