> ## Documentation Index
> Fetch the complete documentation index at: https://timelines.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Partner API Overview

> Programmatically manage TimelinesAI workspaces, users, and WhatsApp connections for your platform

# Partner API

The TimelinesAI Partner API enables B2B partners to programmatically provision and manage workspaces, users, and WhatsApp account connections. This server-to-server API allows partners to integrate TimelinesAI capabilities directly into their own platforms without requiring end-users to interact with the TimelinesAI UI.

> [!NOTE]
>
> The Partner API uses JWT authentication, separate from the Public API's bearer token. See [Getting started](#getting-started) below to set up your partner credentials.

## Billing

Understanding the billing model is essential before provisioning workspaces and connecting WhatsApp accounts.

> [!WARNING]
>
> Partners are invoiced monthly in arrears based on **connected WhatsApp accounts**, not provisioned seats or created users. A WhatsApp account counts toward billing from the moment it is connected until it is explicitly disconnected.

| Concept | How it works |
| - | - |
| **Billing unit** | Each connected WhatsApp account (not seats or users) |
| **Billing cycle** | Monthly in arrears |
| **Seats** | Control the maximum number of users/WhatsApp accounts in a workspace (1–99). Seats are a capacity limit, not a billing unit. |
| **Trials & offboarding** | If a customer trial does not convert, **actively disconnect their WhatsApp account** using `POST /workspaces/{id}/users/{user_id}/whatsapp/disconnect` to stop billing. Simply deleting or ignoring the workspace is not enough — the connected account will continue to be billed. |
| **Seat downgrades** | When you reduce `seats_purchased` below current utilization, the platform may automatically suspend users and their associated WhatsApp accounts to comply with the new limit. |
| **Quota monitoring** | Subscribe to `workspace:seats_full` [Partner API Webhooks](https://timelines.ai/docs/partner-api-webhook-reference/overview.md) to get alerted when all seats are utilized, so you can proactively manage capacity. |

> [!TIP]
>
> Always track the mapping between your customers and their `workspace_id` / `user_id` / WhatsApp account connections. This allows you to promptly disconnect accounts when a customer churns, preventing unnecessary charges.

## Getting started

To begin using the Partner API, you need to have your partner records created in the TimelinesAI system. This is a one-time setup process.

**1. Contact TimelinesAI**

Reach out to TimelinesAI at [support@timelines.ai](mailto:support@timelines.ai) to request partner access. The team will set up your partner records in the system.

**2. Receive your credentials**

Once your partner account is provisioned, you will receive two credentials:

* **Partner ID** — your unique partner identifier (e.g., `your-company-name`)
* **Partner Secret** — a secure key used to sign JWT tokens (keep this confidential)

**3. Generate a JWT token**

Use your credentials to generate a short-lived JWT token for authenticating API requests. See the [Authentication](#authentication) section below for code examples.

**4. Start making API calls**

Include the generated JWT token in the `Authorization` header and your Partner ID in the `X-TL-Partner-Id` header with every request.

## Base URL

```
https://app.timelines.ai/partner/api/v1
```

## Authentication

The Partner API uses JWT (JSON Web Token) bearer authentication. Each request must include a valid JWT token signed with your Partner Secret using the HS256 algorithm.

### Required headers

Include the following headers in all API requests:

| Header | Value |
| - | - |
| `Authorization` | `Bearer <jwt_token>` |
| `X-TL-Partner-Id` | Your partner ID |
| `Content-Type` | `application/json` |

### JWT token generation

Generate a short-lived JWT token with the following payload claims:

| Claim | Type | Description |
| - | - | - |
| `partner_id` | string | Your partner identifier |
| `nbf` | number | Not before — set to 3 minutes in the past (Unix timestamp) |
| `exp` | number | Expiration — set to 3 minutes in the future (Unix timestamp) |

The token must be signed using the **HS256** algorithm with your **Partner Secret**.

```javascript JavaScript theme={null}
const jwt = require('jsonwebtoken');

// Configuration
const PARTNER_ID = 'your-partner-id';
const PARTNER_SECRET = 'your-partner-secret';
const BASE_URL = 'https://app.timelines.ai/partner/api/v1';

// Generate JWT token
function generateToken() {
  const now = Math.floor(Date.now() / 1000);
  return jwt.sign({
    partner_id: PARTNER_ID,
    nbf: now - 180,    // Valid from 3 min ago
    exp: now + 180     // Expires in 3 min
  }, PARTNER_SECRET);
}

// Make authenticated request
async function apiRequest(method, endpoint, body = null) {
  const token = generateToken();
  const options = {
    method: method,
    headers: {
      'Authorization': `Bearer ${token}`,
      'X-TL-Partner-Id': PARTNER_ID,
      'Content-Type': 'application/json'
    }
  };
  if (body) options.body = JSON.stringify(body);

  const response = await fetch(`${BASE_URL}${endpoint}`, options);
  return response.json();
}
```

```python Python theme={null}
import jwt
import requests
from datetime import datetime, timedelta

# Configuration
PARTNER_ID = 'your-partner-id'
PARTNER_SECRET = 'your-partner-secret'
BASE_URL = 'https://app.timelines.ai/partner/api/v1'

# Generate JWT token
def generate_token():
    now = datetime.utcnow()
    payload = {
        'partner_id': PARTNER_ID,
        'nbf': int((now - timedelta(minutes=3)).timestamp()),
        'exp': int((now + timedelta(minutes=3)).timestamp())
    }
    return jwt.encode(payload, PARTNER_SECRET, algorithm='HS256')

# Make authenticated request
def api_request(method, endpoint, json_body=None):
    token = generate_token()
    headers = {
        'Authorization': f'Bearer {token}',
        'X-TL-Partner-Id': PARTNER_ID,
        'Content-Type': 'application/json'
    }
    url = f'{BASE_URL}{endpoint}'
    response = requests.request(method, url, headers=headers, json=json_body)
    return response.json()
```

> [!WARNING]
>
> JWT tokens are short-lived (6-minute window). Generate a fresh token for each API request rather than caching tokens.

## Capabilities

> [card] [Workspaces](https://timelines.ai/docs/partner-api-reference/workspaces/create-a-workspace.md)
>
> Create and manage customer workspaces with configurable seat allocations. Update display names and scale seats up or down.

> [card] [User Management](https://timelines.ai/docs/partner-api-reference/workspaces/create-users-in-workspace.md)
>
> Create placeholder users in batch — each user consumes one seat and can have a WhatsApp account connected.

> [card] [QR Code Onboarding](https://timelines.ai/docs/partner-api-reference/qr/generate-qr-code-for-user.md)
>
> Generate QR code links for users to connect their WhatsApp accounts by scanning. Supports embedded (iframe) and standalone modes.

> [card] [WhatsApp Accounts](https://timelines.ai/docs/partner-api-reference/whatsappaccounts/disconnect-whatsapp-account.md)
>
> Forcibly disconnect WhatsApp accounts from users when needed.

> [card] [API Token Management](https://timelines.ai/docs/partner-api-reference/publicapi/get-public-api-token.md)
>
> Retrieve and rotate Public API tokens for any managed workspace. Tokens don't expire unless explicitly rotated.

## Available endpoints

| Group | Endpoint | Description |
| - | - | - |
| **Workspaces** | `POST /workspaces` | Create a new partner-managed workspace with specified seats |
| | `GET /workspaces/{workspace_id}` | Get workspace details including quotas, users, and WhatsApp accounts |
| | `PATCH /workspaces/{workspace_id}` | Update workspace display name and/or seat count |
| **Users** | `POST /workspaces/{workspace_id}/users` | Create placeholder users in batch (each consumes one seat) |
| **QR Codes** | `POST /workspaces/{workspace_id}/users/{user_id}/qr` | Generate a QR code link for WhatsApp connection |
| **WhatsApp** | `POST /workspaces/{workspace_id}/users/{user_id}/whatsapp/disconnect` | Disconnect a WhatsApp account from a user |
| **API Tokens** | `GET /workspaces/{workspace_id}/api-token` | Retrieve the Public API token (creates one if needed) |
| | `POST /workspaces/{workspace_id}/api-token` | Rotate the Public API token (invalidates the old one immediately) |

## Use case examples

> [accordion] White-label WhatsApp platform
>
> Embed WhatsApp messaging into your own SaaS product without exposing TimelinesAI to your end users.
>
> 1. Use `POST /workspaces` to create a workspace when a customer signs up
> 2. Create users with `POST /workspaces/{id}/users` (one per WhatsApp number they need)
> 3. Generate QR codes with `POST /workspaces/{id}/users/{user_id}/qr` — embed in your UI using `display_mode=embedding`
> 4. Retrieve their Public API token with `GET /workspaces/{id}/api-token`
> 5. Use the Public API token in your backend to send/receive messages on their behalf

> [accordion] Managed service provider
>
> Offer WhatsApp as a service to multiple clients, managing everything from a single integration.
>
> 1. Provision workspaces per client with `POST /workspaces`
> 2. Configure seat allocations with `PATCH /workspaces/{id}`
> 3. Onboard client WhatsApp numbers via QR codes
> 4. Monitor workspace health using Partner API Webhooks (quota alerts, account connectivity)
> 5. Rotate API tokens periodically for security with `POST /workspaces/{id}/api-token`

> [accordion] Automated customer onboarding
>
> Streamline the setup process so new customers can start using WhatsApp within minutes.
>
> 1. Create workspace automatically when customer completes your sign-up flow
> 2. Create users in batch for the number of WhatsApp accounts they need
> 3. Present QR codes in your UI (iframe with `display_mode=embedding` to avoid session logout)
> 4. Listen for `whatsapp_account:connected` webhook to detect successful connection
> 5. Retrieve the Public API token and begin message syncing automatically

> [accordion] Security & compliance management
>
> Maintain control over API access across all managed workspaces.
>
> 1. Rotate Public API tokens periodically with `POST /workspaces/{id}/api-token`
> 2. Subscribe to `api-token:rotated` webhook to track all token changes
> 3. Disconnect compromised WhatsApp accounts with the disconnect endpoint
> 4. Monitor quota webhooks for billing compliance and to prevent service interruption

## Typical integration flow

**1. Create a workspace**

`POST /workspaces` with `display_name` and `seats_purchased` — save the returned `workspace_id` for all subsequent operations

**2. Create users**

`POST /workspaces/{id}/users` with the `count` of users needed — each user consumes one seat

**3. Generate QR codes**

`POST /workspaces/{id}/users/{user_id}/qr` for each user — present the QR link in your UI for WhatsApp scanning

**4. Retrieve API token**

`GET /workspaces/{id}/api-token` — use this token with the Public API to send/receive messages

## QR code embedding

By default, the QR link opens a standalone page. To embed it within your application (e.g., in an iframe), append `display_mode=embedding` to the QR link URL.

| Mode | Behavior |
| - | - |
| **Embedded** (`display_mode=embedding`) | Does **not** log the user out of your application. Optimized for iframe usage. |
| **Standalone** (default) | Opens a full page — **will trigger a logout** from the current session. |

> [!WARNING]
>
> Generating a new QR code disconnects any existing WhatsApp account for that user. Cache and reuse QR links while a connection attempt is active — only request a new one after the previous attempt completes or expires.

## Important notes

> [accordion] API tokens
>
> Public API tokens obtained via `GET /api-token` **do not expire automatically**. A token remains valid indefinitely unless explicitly rotated via `POST /api-token`. The old token is invalidated immediately upon rotation.

> [accordion] Workspace IDs
>
> Always store `workspace_id` and `user_id` mappings in your system. There is currently no list-workspaces endpoint — losing a workspace ID requires a support ticket.

> [accordion] WhatsApp account health
>
> Warm up new WhatsApp accounts before automation — exchange messages with 3–5 contacts first. Poll delivery statuses before running automation sequences. See [WhatsApp mass messaging best practices](https://help.timelines.ai/en/articles/12383621-whatsapp-mass-messaging-best-practices) for details.

## Next steps

> [card] [Partner API Webhooks](https://timelines.ai/docs/partner-api-webhook-reference/overview.md)
>
> Get real-time notifications for workspace events

> [card] [Public API](https://timelines.ai/docs/public-api-reference/overview.md)
>
> Learn about the Public API for message management


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.