API Reference

Base URL: https://api.surt.com

All requests require your API key in the Authorization header.

Create Portal Token

Creates a JWT portal token for initializing FaceGuard in your frontend.

POST /faceguard/session/portal

Request

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": "user_123",
        "email": "customer@example.com",
        "first_name": "John",
        "last_name": "Doe"
    }
}'

Request Body

Field	Type	Required	Description
workflow_id	string	Yes	Your FaceGuard workflow ID from the dashboard
customer	object	Yes	Customer details (see below)

Customer Object

Field	Type	Required	Description
customer_id	string	Yes	Your unique identifier for the user
email	string	No	User's email
first_name	string	No	User's first name
last_name	string	No	User's last name

Response

Response

{
  "status_code": 200,
  "message": "Portal token created",
  "data": {
    "token": "eyJ0eXAiOiJKV1Qi...",
    "customer_id": "user_123"
  }
}

Pass the token to your frontend (SDK, iframe URL, or WebView URL). Portal tokens expire after 30 minutes.

---

Session Endpoints

These endpoints are used internally by the FaceGuard app. They are documented here for reference but are not called directly by integrators.

Create Session

Creates a FaceGuard session from a portal token. Called automatically when FaceGuard loads.

POST /faceguard/session
Authorization: Bearer PORTAL_TOKEN

Get Session Status

Polls the latest session status using the portal token. Used by the QR code flow to detect when the mobile user completes verification.

GET /faceguard/session/status
Authorization: Bearer PORTAL_TOKEN

---

Shortcode Endpoints

Used by the QR code flow for phone handoff.

Method	Path	Auth	Description
POST	/faceguard/short-code	Portal JWT	Create a shortcode
PUT	/faceguard/short-code	Portal JWT	Refresh a shortcode
GET	/faceguard/short-code?code=ABC123	Public	Redeem a shortcode

Response Envelope

All responses use the standard Surt envelope:

{
  "status_code": 200,
  "message": "Success",
  "data": { ... }
}