---
title: Overview & Authentication
sidebar_position: 1
---

# Client API Overview & Authentication

The **Client API** allows you to integrate external, third-party end-users, mobile apps, or custom web portals with the Firetell voice platform. Unlike the Agent API (which is designed for call center agents registered in the database), the Client API allows you to authenticate _any_ custom username on-the-fly using a signed JSON Web Token (JWT).

---

## 1. Authentication & JWT Payload

To connect a client device via the SDK, your backend must generate and sign a JWT using the **Secret Key** of one of your workspace API Keys. The JWT must contain the following claims:

| Claim          | Type     | Required | Description                                                                    |
| :------------- | :------- | :------- | :----------------------------------------------------------------------------- |
| `iss`          | `string` | **Yes**  | The API Key SID (`sid-...`) used to sign the token.                            |
| `aud`          | `string` | **Yes**  | Must be set to `client-api`.                                                   |
| `sub`          | `string` | **Yes**  | Unique external username/ID (1-64 chars. Allowed: alphanumeric, `_`, `-`, `.`. No `@` or spaces). |
| `domain`       | `string` | **Yes**  | Your workspace domain (e.g., `company.firetell.com`).                          |
| `exp`          | `number` | **Yes**  | Expiration timestamp in seconds (Unix epoch time).                             |
| `call_flow_id` | `string` | **Yes**  | The outbound Call Flow ID that will handle outbound calls made by this client. |

### Payload Example

```json
{
  "iss": "sid-650000000000000000000001",
  "aud": "client-api",
  "sub": "partner_customer_100",
  "domain": "acme.firetell.com",
  "exp": 1786022400,
  "call_flow_id": "cf_650000000000000000000100"
}
```

:::important Subject (sub) Validation Rules
To ensure secure and reliable connection handling and avoid formatting conflicts:
- **Allowed characters:** Alphanumeric (`a-z`, `A-Z`, `0-9`), underscores (`_`), hyphens (`-`), and dots (`.`).
- **Forbidden characters:** Special characters, whitespaces, and specifically the `@` symbol are strictly prohibited.
- **Length:** The `sub` value must be between **1 and 64 characters** long.
:::

---

## 2. Dynamic Connection Quotas & Limits

To protect the infrastructure from misuse or intentional DDoS attacks, the following limits are strictly enforced on Client API connections:

- **Per-User Session Limit:** A single user ID (`sub`) can have a maximum of **5 concurrent active sessions** (e.g., open tabs or devices).
- **Workspace Limit:** All Client API connections in a single workspace are capped at a total of **1000 concurrent active connections**.

:::warning Requesting Limit Increases
If your production application requires higher concurrent connection capacities, please contact our support team at [enterprise@firetell.com](mailto:enterprise@firetell.com) to request custom quotas.
:::

---

## 3. Real-Time Events (`call.ring`)

Clients receive real-time updates (such as incoming call alerts) via a Server-Sent Events (SSE) stream at `/stream?token={JWT}`:

- **Incoming Call Notification (`call.ring`):**
  When a call is routed to the client, the client device receives a `call.ring` event to trigger the ringer UI:
  ```json
  {
    "event": "call.ring",
    "call_id": "call_1770000000000",
    "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "ws_url": "wss://yourcompany.firetell.app/ws",
    "from": {
      "number": "agent_username",
      "name": "Your driver"
    },
    "to": {
      "number": "partner_customer_100",
      "name": "Partner Customer Name"
    },
    "timestamp": "2026-07-30T16:07:00.000Z"
  }
  ```

---

## 4. Outbound Calling Rule (`call_flow_id`)

When a client initiates an outbound call via the Client SDK (by calling the `makeCall` API), the following rules apply:

- **Strict Call Flow Routing:** The call **must** be routed through the outbound Visual Call Flow identified by the `call_flow_id` claim in the client's JWT token.
- **Pre-requisite:** The call flow assigned to `call_flow_id` must be pre-configured in the Workspace Portal and have its `trigger_type` set to `outbound`.
- **Security & Control:** This restriction ensures that end-user calls are securely monitored, formatted, recorded (if configured), and filtered according to your business's outbound calling rules before routing to carriers or external DIDs.

---

## 5. Integrating with Client SDK

Once you have generated a valid Client JWT on your backend, you can pass it to our official frontend Client SDK to initialize the real-time event stream, handle WebRTC audio/video connections, and manage the calling lifecycle on the device.

To install the SDK, import it, and see complete usage guides, please refer to the [Client SDK Integration Guide](https://developers.firetell.com/docs/sdks/overview).

---

## 6. REST API Reference

If you are implementing your own WebRTC signaling/client wrapper without using the official Client SDK, you can call the make call REST API directly using your Client JWT.

### Initiate Outbound Call

Initiate an outbound WebRTC call and receive the signaling WebSocket session details.

* **Endpoint:** `POST /api/v1/call-center/calls/make`
* **Headers:**
  * `Authorization: Bearer <client-api-jwt>`
  * `Content-Type: application/json`

#### Request Body
```json
{
  "to": "agent_username",
  "from": "",
  "type": "audio"
}
```

#### Response Example (`201 Created`)
```json
{
  "call_id": "call_1770000000000",
  "ws_url": "wss://yourcompany.firetell.app/call-session",
  "call_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

After receiving this response, the client must connect to `ws_url` and send a `session.connect` event with the `call_token` within 3 seconds to complete signaling authentication.