API Integration Guide

API Integration Guide

The Partner API enables you to integrate account verification into your application. Users verify their accounts through an iframe-based browser session, and you receive cryptographically attested proof of data authenticity.

Authentication

All Partner API endpoints require authentication via your API key:

x-api-key: your_api_key_here

Alternatively, you can use the Authorization header:

Authorization: Bearer your_api_key_here

All requests must include Content-Type: application/json.

Response Format

All responses are wrapped in a standard envelope:

{
  "status": "success",
  "data": { ... }
}

Error responses return the appropriate HTTP status code with error details in the body.

---

Endpoints

Get Available Platforms

Retrieves the list of verification platforms available for browser sessions.

GET /partner/browser-platforms

Headers

Header	Required	Description
x-api-key	Yes	Your partner API key

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "uber",
      "displayName": "Uber",
      "description": "Uber driver account verification",
      "icon": "https://...",
      "loginUrl": "https://auth.uber.com/v2",
      "allowCustomUrl": false,
      "config": {},
      "isActive": true,
      "createdAt": "2025-01-15T00:00:00.000Z",
      "updatedAt": "2025-02-01T00:00:00.000Z"
    }
  ]
}

Field	Type	Description
id	number	Platform identifier (use this as platformId when creating sessions)
name	string	Unique platform slug
displayName	string	Human-readable platform name
description	string | null	Platform description
icon	string | null	Platform logo URL
loginUrl	string	Default login URL for this platform
allowCustomUrl	boolean	Whether custom URLs are permitted
config	object | null	Platform-specific configuration
isActive	boolean	Whether the platform is currently available
createdAt	string	ISO 8601 creation timestamp
updatedAt	string | null	ISO 8601 last update timestamp

---

Create Browser Session

Initiates a new verification session for a given platform.

POST /partner/browser-session

Headers

Header	Required	Description
x-api-key	Yes	Your partner API key
Content-Type	Yes	application/json

Request Body

{
  "platformId": 1,
  "receiverData": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "expiresInHours": 24,
  "webhookUrl": "https://your-app.com/webhooks/cr3dentials",
  "externalReferenceId": "user_abc123"
}

Field	Type	Required	Description
platformId	number	Yes	Platform ID from the platforms endpoint
receiverData	object	No	Metadata about the person performing verification (name, email, phone, etc.)
expiresInHours	integer	No	Session TTL in hours. Range: 1–168 (7 days). Defaults to maximum if not provided
webhookUrl	string	No	HTTPS URL to receive session status webhooks. Must use HTTPS with a valid TLD
externalReferenceId	string	No	Your internal reference ID for tracking this session

Response

{
  "status": "success",
  "data": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "CREATED",
    "embedUrl": "https://frame.cr3dentials.xyz/verify/a1b2c3d4...?token=xxx",
    "platformId": 1,
    "expiresAt": "2025-03-25T12:00:00.000Z",
    "createdAt": "2025-03-24T12:00:00.000Z",
    "externalReferenceId": "user_abc123"
  }
}

Field	Type	Description
sessionId	string	Unique session identifier (UUID)
status	string	Initial session status (CREATED)
embedUrl	string	URL for iframe embedding — load this in your UI
platformId	number	Platform ID for this session
expiresAt	string	ISO 8601 expiration timestamp
createdAt	string	ISO 8601 creation timestamp
externalReferenceId	string	Only present if provided in the request

---

Get Browser Session

Retrieves the current status and results of a browser session. Use this to poll for session completion or check verification results.

GET /partner/browser-session/:id

Headers

Header	Required	Description
x-api-key	Yes	Your partner API key

Path Parameters

Parameter	Description
id	The sessionId returned from session creation

Response

{
  "status": "success",
  "data": {
    "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "status": "COMPLETED",
    "progress": 100,
    "embedUrl": "https://frame.cr3dentials.xyz/verify/a1b2c3d4...?token=xxx",
    "streamUrl": "wss://stream.cr3dentials.xyz/session/a1b2c3d4...",
    "platformId": 1,
    "platform": {
      "id": 1,
      "name": "uber",
      "displayName": "Uber",
      "icon": "https://..."
    },
    "expiresAt": "2025-03-25T12:00:00.000Z",
    "createdAt": "2025-03-24T12:00:00.000Z",
    "completedAt": "2025-03-24T12:05:00.000Z",
    "hasAttestation": true,
    "extractedData": {
      "accountHolder": "John Doe",
      "accountType": "checking",
      "lastFourDigits": "1234"
    }
  }
}

Field	Type	Description
sessionId	string	Session identifier
status	string	Current session status (see Session Lifecycle)
progress	number	Verification progress percentage (0–100)
embedUrl	string	Iframe embed URL
streamUrl	string | null	WebSocket stream URL (when session is active)
platformId	number	Platform ID
platform	object	Platform details (id, name, displayName, icon, loginUrl)
expiresAt	string	ISO 8601 expiration timestamp
createdAt	string	ISO 8601 creation timestamp
completedAt	string | null	ISO 8601 completion timestamp (only for terminal states)
errorMessage	string | null	Error description (only when status is ERROR)
errorCode	string | null	Machine-readable error code (only when status is ERROR)
hasAttestation	boolean	Present and true when cryptographic attestation is available
extractedData	object | null	Verified account data (only when verification is complete)

Note: The full attestation object is not returned in this endpoint. hasAttestation indicates that a cryptographic proof exists for this session.

---

List Browser Sessions

Returns a paginated list of browser sessions created by your API key.

GET /partner/browser-sessions

Headers

Header	Required	Description
x-api-key	Yes	Your partner API key

Query Parameters

Parameter	Type	Required	Description
status	string	No	Filter by session status (e.g., COMPLETED, ERROR)
limit	integer	No	Results per page. Range: 1–100. Default: 20
offset	integer	No	Pagination offset. Default: 0

Response

{
  "status": "success",
  "data": {
    "sessions": [
      {
        "sessionId": "a1b2c3d4-...",
        "status": "COMPLETED",
        "platformId": 1,
        "createdAt": "2025-03-24T12:00:00.000Z",
        "completedAt": "2025-03-24T12:05:00.000Z"
      }
    ],
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

Field	Type	Description
sessions	array	Array of session objects
total	number	Total number of sessions matching the filter
limit	number	The limit used for this request
offset	number	The offset used for this request

---

Session Lifecycle

Sessions progress through the following statuses:

Status	Description
CREATED	Session created, browser environment not yet assigned
INITIALIZING	Browser environment spinning up
READY	Browser ready, waiting for user to connect
CONNECTED	User connected via iframe, can interact with the browser
LOADING_TREE	Session agent is loading the verification workflow
RUNNING	Executing verification steps
AWAITING_USER	Waiting for user action (login, 2FA, security questions)
COLLECTING_DATA	Extracting account data after successful login
VERIFYING	Generating cryptographic attestation

Terminal statuses:

Status	Description
COMPLETED	Verification successful — attestation and extracted data available
PARTIAL_COMPLETE	Verification partially succeeded — some data was collected but the full workflow did not complete
ERROR	An error occurred — check errorMessage and errorCode
CANCELLED	User cancelled the session
TERMINATED	Session was terminated (manually or due to expiration)

---

Webhooks

When you provide a webhookUrl during session creation, we send a POST request to your endpoint when the session reaches a terminal status (COMPLETED, PARTIAL_COMPLETE, ERROR, CANCELLED, TERMINATED).

Requirements:

• Must be a valid HTTPS URL with a valid TLD

• Must respond with a 2xx status code within 30 seconds

Webhook Payload:

{
  "sessionId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "status": "COMPLETED",
  "externalReferenceId": "user_abc123",
  "extractedData": {
    "accountHolder": "John Doe",
    "accountType": "checking"
  },
  "completedAt": "2025-03-24T12:05:00.000Z"
}

---

Rate Limits

API endpoints enforce rate limits to ensure fair usage:

• Global limit: 120 requests per 60 seconds per API key

• Session creation and bulk operations have additional per-endpoint limits

When rate limited, you'll receive a 429 Too Many Requests response. Implement exponential backoff in your retry logic.

---

Security

• All browser sessions run in isolated environments — no credentials are stored or transmitted to CR3DENTIALS servers

• Iframe access is secured with short-lived, single-use tokens

• Webhook URLs must use HTTPS

• API keys can be rotated at any time via the dashboard

• Zero-knowledge proof protocols ensure data authenticity without exposing raw credentials