> For the complete documentation index, see [llms.txt](https://docs.firework.com/firework-for-developers/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.firework.com/firework-for-developers/api/businesses.md).

# Businesses

### 1. Overview

The Firework Business API returns the businesses your access token is allowed to act on. It is the entry point for discovering a `business_id` before calling business-scoped endpoints such as `GET /api/v1/channels`.

Which businesses are returned depends on the token type:

* **OAuth app token** (Client Credentials): returns the single business the app is connected to.
* **User token**: returns all businesses the user is a member of.

Use the `id` returned by this endpoint as the `business_id` query parameter on business-scoped endpoints.

> This API provides read-only access. Businesses are created and managed through the Firework dashboard.

**Base URL**: `https://api.firework.com`

### 2. Authentication

The Firework Business API uses OAuth 2.0 for authentication. Before using this API, you must obtain an access token.

**Authentication Methods Supported:**

* **Client Credentials**: OAuth 2.0 Client Credentials flow for server-to-server authentication (machine-to-machine)

> 📖 **Documentation:**
>
> * [Client Credentials OAuth](/firework-for-developers/api/authentication.md) - Server-to-server authentication for OAuth apps

***

### 3. Endpoint Summary

| Endpoint                 | Scope             | Notes                                    |
| ------------------------ | ----------------- | ---------------------------------------- |
| `GET /api/v1/businesses` | `businesses:read` | List the businesses the token can act on |

***

### 4. List Businesses

Retrieve the businesses available to the authenticated token. For an OAuth app token this is the token's own business; for a user token it is the businesses the user belongs to. Use a returned `id` as the `business_id` parameter on business-scoped endpoints.

**Endpoint**: `GET /api/v1/businesses` **Authentication**: Bearer token required (OAuth 2.0 Client Credentials) **Required Scope**: `businesses:read` (for OAuth apps)

#### 4.1. Request Headers

| Name            | Description                           | Required |
| --------------- | ------------------------------------- | -------- |
| `Authorization` | Bearer token: `Bearer {ACCESS_TOKEN}` | ✅        |

#### 4.2. Query Parameters

This endpoint takes no query parameters. The result set is determined entirely by the authenticated token, and the response is not paginated.

#### 4.3. List Businesses Response

**Success Response**: `200 OK`

```json
{
  "businesses": [
    {
      "id": "J1BA8n",
      "name": "My Business",
      "country": "US"
    }
  ]
}
```

An OAuth app token whose app is not connected to a business returns an empty array: `{ "businesses": [] }`.

**Business Fields**

| Field     | Type   | Nullable | Description                                                   |
| --------- | ------ | -------- | ------------------------------------------------------------- |
| `id`      | string | ❌        | Encoded unique identifier. Use as `business_id` in other APIs |
| `name`    | string | ✅        | Display name of the business                                  |
| `country` | string | ✅        | Two-letter country code (e.g., `"US"`, `"CA"`)                |

#### 4.4. List Businesses Error Responses

| Status Code        | Description                             |
| ------------------ | --------------------------------------- |
| `401 Unauthorized` | Invalid or missing authentication token |
| `403 Forbidden`    | Insufficient scope for OAuth app        |

**Error Response Format**:

```json
{
  "error": "Error Message"
}
```

#### 4.5. Examples

**CURL Request**

```bash
curl -X GET "https://api.firework.com/api/v1/businesses" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```