API Integration Guide

Partner API Integration Guide (Browser Sessions)

Overview

The Partner API provides endpoints for creating and managing browser-based verification sessions. This API allows partners to embed CR3DENTIALS verification directly in their applications using an iframe-based approach with isolated, secure browser sessions.

Key Features:

Embedded iframe experience — Users verify accounts directly in your app
zkTLS verification — Cryptographically proven data without storing credentials
Real-time webhooks — Instant notifications when verification completes
Secure isolation — Each session runs in a completely isolated browser environment

Authentication

The Partner API uses API Key authentication for all endpoints.

Headers

Header

Description

x-api-key

Your partner API key (required for all endpoints)

Content-Type

application/json

Example

curl -X POST https://api.cr3dentials.xyz/partner/browser-session \
  -H "x-api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"platformId": 1}'

Endpoints

List Browser Platforms

Returns a list of all active browser platforms available for verification sessions. Use this endpoint to display platform options to users.

GET /partner/browser-platforms

Authentication: API Key required

Response

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "uber",
      "displayName": "Uber",
      "description": "Uber Income",
      "icon": "https://cdn.cr3dentials.xyz/logos/uber.png",
      "loginUrl": "https://uber.com/web/auth/login",
      "allowCustomUrl": false,
      "isActive": true,
      "createdAt": "2025-01-15T10:00:00.000Z",
      "updatedAt": "2025-01-20T14:30:00.000Z"
    }
  ]
}

Response Fields

Field

Type

Description

id

number

Platform ID (use this when creating sessions)

name

string

Unique platform identifier

displayName

string

Human-readable platform name

description

string

Platform description

icon

string

Platform logo URL

loginUrl

string

Default login URL

allowCustomUrl

boolean

Whether custom URLs are allowed

isActive

boolean

Platform availability status

createdAt

string

Creation timestamp

updatedAt

string

Last update timestamp

Create Browser Session

Creates a new browser verification session. Returns an embed URL for iframe integration.

POST /partner/browser-session

Authentication: API Key required

Request Body

{
  "platformId": 1,
  "receiverData": {
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890"
  },
  "expiresInHours": 1,
  "webhookUrl": "https://api.partner.com/webhooks/verification",
  "externalReferenceId": "partner-ref-12345"
}

Request Parameters

Parameter

Type

Required

Description

platformId

number

Yes

Platform ID (must match a configured BrowserPlatform)

receiverData

object

External receiver data (name, email, phone, etc.)

expiresInHours

number

Session expiration in hours (1-24, default: 1)

webhookUrl

string

HTTPS webhook URL for status updates

externalReferenceId

string

Your tracking ID (included in responses/webhooks)

Response

{
  "status": "success",
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "CREATED",
    "embedUrl": "https://verify.cr3dentials.xyz/session/550e8400-e29b-41d4-a716-446655440000?token=abc123...",
    "platformId": 1,
    "expiresAt": "2025-01-30T11:30:00.000Z",
    "createdAt": "2025-01-30T10:30:00.000Z",
    "externalReferenceId": "partner-ref-12345"
  }
}

Get Browser Session Details

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

GET /partner/browser-session/:id

Authentication: API Key required

Parameters

Parameter

Type

Description

id

string (path)

Session ID (UUID)

Response

{
  "status": "success",
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "progress": 100,
    "embedUrl": "https://verify.cr3dentials.xyz/session/...",
    "streamUrl": "wss://stream.cr3dentials.xyz/...",
    "platformId": 1,
    "platform": {
      "id": 1,
      "name": "Chase Bank",
      "logoUrl": "https://cdn.cr3dentials.xyz/logos/chase.png"
    },
    "expiresAt": "2025-01-30T11:30:00.000Z",
    "createdAt": "2025-01-30T10:30:00.000Z",
    "completedAt": "2025-01-30T10:35:00.000Z",
    "hasAttestation": true,
    "extractedData": {
      "accountHolder": "John Doe",
      "totalIncome": 75000,
      "currency": "USD",
      "period": "2024-01-01 to 2024-12-31",
      "transactionCount": 24
    }
  }
}

Response Fields

Field

Type

Description

sessionId

string

Unique session identifier

status

string

Current session status (see Session Statuses)

progress

number

Verification progress (0-100)

embedUrl

string

URL for iframe embedding

streamUrl

string

WebRTC stream URL (when connected)

platformId

number

Platform ID

platform

object

Platform details (name, logo)

expiresAt

string

Session expiration timestamp

createdAt

string

Session creation timestamp

completedAt

string

Completion timestamp (if completed)

errorMessage

string

Error description (if failed)

errorCode

string

Error code (if failed)

hasAttestation

boolean

Whether attestation is available

extractedData

object

Verified data (if completed)

List Browser Sessions

Returns a paginated list of browser sessions created by your partner account.

GET /partner/browser-sessions

Authentication: API Key required

Query Parameters

Parameter

Type

Default

Description

status

string

—

Filter by session status

limit

number

Results per page (max: 100)

offset

number

Pagination offset

Response

{
  "status": "success",
  "data": {
    "sessions": [
      {
        "sessionId": "550e8400-e29b-41d4-a716-446655440000",
        "status": "COMPLETED",
        "platformId": 1,
        "createdAt": "2025-01-30T10:30:00.000Z",
        "completedAt": "2025-01-30T10:35:00.000Z"
      }
    ],
    "total": 150,
    "limit": 20,
    "offset": 0
  }
}

Session Statuses

Active States

Status

Description

CREATED

Session created, awaiting user connection

INITIALIZING

Browser pod spinning up

READY

Pod ready, waiting for user

CONNECTED

User connected via iframe

LOADING_TREE

Loading verification flow

RUNNING

Executing verification steps

AWAITING_USER

Waiting for user action (login, 2FA)

COLLECTING_DATA

Collecting data from user's account

VERIFYING

Generating attestation

Terminal States (Immutable)

Status

Description

COMPLETED

Verification successful, attestation available

TERMINATED

Session manually terminated

ERROR

Verification failed

CANCELLED

User cancelled the session

Webhook Integration

When you provide a webhookUrl during session creation, we'll POST updates to your endpoint when the session reaches a terminal state.

Webhook Payload

{
  "event": "browser_session.completed",
  "timestamp": "2025-01-30T10:35:00.000Z",
  "data": {
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "status": "COMPLETED",
    "platformId": 1,
    "externalReferenceId": "partner-ref-12345",
    "attestation": {
      "issuer": "cr3dentials.xyz",
      "timestamp": "2025-01-30T10:35:00.000Z",
      "signature": "0x...",
      "verificationHash": "sha256:..."
    },
    "extractedData": {
      "accountHolder": "John Doe",
      "totalIncome": 75000,
      "currency": "USD",
      "period": "2024-01-01 to 2024-12-31"
    },
    "completedAt": "2025-01-30T10:35:00.000Z"
  }
}

Webhook Requirements

URL must be HTTPS with a valid TLD
Respond with 2xx status code within 30 seconds
We retry failed deliveries (3 attempts with exponential backoff)

Typical Workflow

1. Get Available Platforms

curl -X GET https://api.cr3dentials.xyz/partner/browser-platforms \
  -H "x-api-key: your-api-key"

2. Create a Browser Session

Use the platformId from the platforms list:

curl -X POST https://api.cr3dentials.xyz/partner/browser-session \
  -H "x-api-key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "platformId": 1,
    "webhookUrl": "https://yourapp.com/webhooks/verification",
    "externalReferenceId": "user_123"
  }'

3. Embed the Iframe

<iframe
  src="https://verify.cr3dentials.xyz/session/SESSION_ID?token=TOKEN"
  width="100%"
  height="600"
  allow="camera; microphone"
></iframe>

4. Receive Results

Via webhook or polling GET /partner/browser-session/:id

4. Receive Results

Option A: Webhook (Recommended)

Your webhook endpoint receives the verification result automatically when complete.

Option B: Polling

Poll the session status endpoint until status is a terminal state:

curl -X GET https://api.cr3dentials.xyz/partner/browser-session/SESSION_ID \
  -H "x-api-key: your-api-key"

Error Handling

Error Response Format

{
  "statusCode": 500,
  "message": "Failed to create browser session. Please try again or contact support."
}

Common Error Codes

Code

Description

400

Bad Request — Invalid parameters

401

Unauthorized — Invalid or missing API key

404

Not Found — Session not found or not owned by you

500

Internal Server Error

Rate Limiting

Session creation is rate-limited per API key
Limits are configurable per partner agreement
Exceeded limits return 429 Too Many Requests

Quick Reference

Method

Endpoint

Authentication

Description

GET

/partner/browser-platforms

API Key

List available platforms

POST

/partner/browser-session

API Key

Create browser session

GET

/partner/browser-session/:id

API Key

Get session details

GET

/partner/browser-sessions

API Key

List sessions

Security Features

Session Isolation — Each verification runs in a completely isolated browser environment
Token-Based Access — Embed URLs include cryptographically secure access tokens
Token Invalidation — Access tokens are invalidated when sessions reach terminal state
zkTLS Proofs — Cryptographic proof that data came from the claimed platform
No Credential Storage — User credentials are never transmitted to our backend

Support

For API support or integration questions, contact your partner integration manager or email [email protected].

PreviousPartner Portal Guide NextWebhooks

Last updated 1 month ago

hashtagPartner API Integration Guide (Browser Sessions)

hashtagOverview

hashtagAuthentication

hashtagHeaders

hashtagExample

hashtagEndpoints

hashtagList Browser Platforms

hashtagCreate Browser Session

hashtagGet Browser Session Details

hashtagList Browser Sessions

hashtagSession Statuses

hashtagActive States

hashtagTerminal States (Immutable)

hashtagWebhook Integration

hashtagWebhook Payload

hashtagWebhook Requirements

hashtagTypical Workflow

hashtag1. Get Available Platforms

hashtag2. Create a Browser Session

hashtag3. Embed the Iframe

hashtag4. Receive Results

hashtag4. Receive Results

hashtagError Handling

hashtagError Response Format

hashtagCommon Error Codes

hashtagRate Limiting

hashtagQuick Reference

hashtagSecurity Features

hashtagSupport

Partner API Integration Guide (Browser Sessions)

Overview

Authentication

Headers

Example

Endpoints

List Browser Platforms

Create Browser Session

Get Browser Session Details

List Browser Sessions

Session Statuses

Active States

Terminal States (Immutable)

Webhook Integration

Webhook Payload

Webhook Requirements

Typical Workflow

1. Get Available Platforms

2. Create a Browser Session

3. Embed the Iframe

4. Receive Results

4. Receive Results

Error Handling

Error Response Format

Common Error Codes

Rate Limiting

Quick Reference

Security Features

Support