# 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:

```json
{
  "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**

```json
{
  "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**

```json
{
  "platformId": 1,
  "receiverData": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "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**

```json
{
  "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**

```json
{
  "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**

```json
{
  "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:**

```json
{
  "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