Authentication

1. Overview

Firework Public API supports OAuth 2.0 Client Credentials flow for server-to-server authentication. This authentication method is designed for backend applications that need to access Firework APIs without user interaction.

Production Base URL: <https://api.firework.com>

⚠️ Important:

• OAuth apps must be registered and configured by the Firework IS (Integration Solutions) team before use

• Client credentials are scoped to your business. You can only access resources (videos, channels, live streams) that belong to your business

• OAuth apps must be granted specific scopes that determine which API endpoints they can access

• Client credentials authentication is only supported for /api/v1/* Public API endpoints

2. OAuth App Registration

Before using the Client Credentials flow, you must have an OAuth app registered by the Firework IS team.

2.1. Registration Process

Contact the Firework IS team to register your OAuth app. Provide the following information:

1. Business ID - The Firework business that will own the OAuth app

2. App Name - A descriptive name for your application

3. Required Scopes - The specific scopes your app needs (see section 2.2)

The IS team will provide you with:

• client_id - Your OAuth app's unique identifier

• client_secret - Your OAuth app's secret key (store securely!)

2.2. Available Scopes

OAuth apps must be granted one or more scopes that determine which API endpoints they can access:

Endpoint	Scope	Description
POST /api/v1/upload_signatures	videos:write	Get pre-signed credentials for S3 upload
POST /api/v1/upload_multipart/signatures	videos:write	Initiate multipart upload
POST /api/v1/upload_multipart/complete	videos:write	Complete a multipart upload
POST /api/v1/videos	videos:write	Create videos
GET /api/v1/videos/{id}	videos:read	Read video details
PATCH /api/v1/videos/{id}	videos:write	Update videos
GET /api/v1/products/{product_id}/videos	products:read	List videos for a product
GET /api/v1/live_streams/{id}/detail	livestreams:read	Get live stream details
POST /api/v1/live_streams/{id}/pin_product	livestreams:write	Pin products to live stream
POST /api/v1/live_streams/{id}/unpin_product	livestreams:write	Unpin products from live stream
PATCH /api/v1/live_streams/{id}/end	livestreams:write	End a live stream
All Public API endpoints	api:admin	Full administrative access

📝 Note:

• Request only the minimum scopes your application needs (principle of least privilege)

• The api:admin scope bypasses all scope checks and should be used sparingly

• Scopes are set during OAuth app registration and cannot be changed via API

• Scope Hierarchy: Write scopes automatically grant read access. For example, livestreams:write grants both read and write operations, and videos:write grants both read and write access to videos

---

3. Client Credentials Flow

The authentication process has two steps:

1. Get Access Token - Exchange client credentials for an access token

2. Use Access Token - Include token in API requests

---

4. Endpoint Summary

Endpoint	Status	Notes
POST /oauth/token	✅ Implemented	Get access token

---

5. Get Access Token

Exchange your client credentials for an access token.

Endpoint: POST /oauth/token Authentication: None required Token lifetime: 1 hour

5.1. Request Parameters

Parameter	Type	Required	Description
grant_type	string	✅	Must be "client_credentials"
client_id	string	✅	Your OAuth app's Client ID
client_secret	string	✅	Your OAuth app's Client Secret
scope	string	✅	Space-separated list of requested scopes (must be subset of app's allowed scopes)

5.2. Get Access Token Response

Success Response: 200 OK

Field	Type	Nullable	Description
access_token	string	❌	JWT bearer token for API authentication (contains scope in JWT claims)
expires_in	number	❌	Token lifetime in seconds (3600)

5.3. Examples

CURL Request

curl -X POST "<https://api.firework.com/oauth/token>" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id={CLIENT_ID}" \ -d "client_secret={CLIENT_SECRET}" \ -d "scope=videos:write livestreams:write"

Example Response

{ "access_token": "{ACCESS_TOKEN}", "expires_in": 3600 }

📝 Note: The granted scopes are embedded within the JWT token claims. You can decode the JWT to see the scope field which contains the scopes that were granted for this token. The token also includes a bid (business ID) claim that scopes the token to your business.

---

6. Using Access Tokens

Include the access token in the Authorization header for all API requests:

Authorization: Bearer {ACCESS_TOKEN}

Important:

• Client credentials access tokens are only valid for /api/v1/* Public API endpoints

• Your OAuth app must have the required scope to access each endpoint

• Requests without the required scope will return 403 Forbidden with an insufficient_scope error

6.1. Supported Endpoints and Required Scopes

The following Firework Public API v1 endpoints support client credentials authentication:

Video Management (requires videos:write scope)

• POST /api/v1/videos - Create/upload video

• PATCH /api/v1/videos/:id - Update video metadata

Live Stream Management (requires livestreams:write scope)

• POST /api/v1/live_streams/:id/pin_product - Pin products to live stream (max 3 products per request)

• POST /api/v1/live_streams/:id/unpin_product - Unpin products from live stream (max 3 products per request)

• PATCH /api/v1/live_streams/:id/end - End a live stream

Live Stream Read-Only (requires livestreams:read scope)

• GET /api/v1/live_streams/:live_stream_id/detail - Get live stream details

📝 Note:

• OAuth apps with the api:admin scope can access all endpoints regardless of other scope requirements

• OAuth apps with livestreams:write scope can also access read-only livestream endpoints (write scope grants read access)

6.2. Example API Requests

Create/Upload Video

curl -X POST "<https://api.firework.com/api/v1/videos>" \ -H "Authorization: Bearer {ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "url": "<https://example.com/video.mp4>", "channel_id": "abc123", "caption": "Product Demo", "hashtags": ["demo", "product"], "product_ids": ["prod_123", "prod_456"] }'

Pin Products to Live Stream

curl -X POST "<https://api.firework.com/api/v1/live_streams/{LIVE_STREAM_ID}/pin_product>" \ -H "Authorization: Bearer {ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "product_ids": ["prod_123", "prod_456", "prod_789"] }'

Unpin Products from Live Stream

curl -X POST "<https://api.firework.com/api/v1/live_streams/{LIVE_STREAM_ID}/unpin_product>" \ -H "Authorization: Bearer {ACCESS_TOKEN}" \ -H "Content-Type: application/json" \ -d '{ "product_ids": ["prod_123", "prod_456"] }'

End Live Stream

curl -X PATCH "<https://api.firework.com/api/v1/live_streams/{LIVE_STREAM_ID}/end>" \ -H "Authorization: Bearer {ACCESS_TOKEN}" \ -H "Content-Type: application/json"

Get Live Stream Details (Read-Only)

curl -X GET "<https://api.firework.com/api/v1/live_streams/{LIVE_STREAM_ID}/detail>" \ -H "Authorization: Bearer {ACCESS_TOKEN}"