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

{
  "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:

{
  "error": "Error Message"
}

4.5. Examples

CURL Request

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