Authentication

The Firework Public API uses OAuth 2.0 for authentication. You must obtain an access token before making API calls to any Firework endpoints.

1. OAuth 2.0 Flow

The authentication process follows the standard OAuth 2.0 authorization code flow:

1. Get Authorization Code

2. Get Access Token

3. Refresh Access Token (when needed)

---

2. Endpoint Summary

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

Endpoint	Notes
GET /oauth/authorize	Get authorization code
POST /oauth/token	Get the access token or the refresh token

---

3. Get Authorization Code

Direct users to the authorization URL to obtain an authorization code.

Endpoint: GET /oauth/authorize Authentication: None required

3.1 Query Parameters

Parameter	Type	Required	Description
response_type	string	✅	Must be "code"
redirect_uri	string	✅	Must match a registered redirect URI
client_id	string	✅	Your OAuth client ID
state	string	❌	Random string to prevent CSRF attacks and preserve context
scope	string	✅	Must be "openid"

3.2 Get Authorization Code Response

Success Response: 301 Redirect

Users will be redirected to your redirect_uri with the authorization code and state parameter.

3.3 Examples

Authorization URL

GET

https://api.firework.com/oauth/authorize?response_type=code&redirect_uri=https://your-app.com/oauth_callback&client_id={CLIENT_ID}&state={STATE}&scope=openid

Example Response

HTTP 301 Redirect

https://your-app.com/oauth_callback?code={AUTHORIZATION_CODE}&state={STATE}

---

4. Get Access Token

Exchange the authorization code for an access token.

Endpoint: POST /oauth/token Authentication: None required

4.1 Query Parameters

Parameter	Type	Required	Description
grant_type	string	✅	Must be "authorization_code"
redirect_uri	string	✅	Must match the redirect URI used in step 1
client_id	string	✅	Your OAuth client ID
client_secret	string	✅	Your OAuth client secret
code	string	✅	Authorization code from step 1

4.2 Get Access Token Response

Success Response: 200 OK

Field	Type	Nullable	Description
access_token	string	❌	JWT access token for API requests
refresh_token	string	❌	Token for refreshing access tokens
token_type	string	❌	Always "bearer"
scope	string	❌	Granted scope ("openid")
token_expires_in	number	❌	Access token lifetime in seconds (7200)
refresh_token_expires_in	number	❌	Refresh token lifetime in seconds (600000)
created_at	string	❌	ISO 8601 timestamp of token creation

4.3 Examples

CURL Request

curl -X POST "https://api.firework.com/oauth/token?grant_type=authorization_code&redirect_uri=https://your-app.com/oauth_callback&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}&code={AUTHORIZATION_CODE}"

Example Response

{ "refresh_token": "YOUR_REFRESH_TOKEN", "scope": "openid", "access_token": "YOUR_ACCESS_TOKEN", "token_type": "bearer", "created_at": "2021-01-21T00:05:31Z", "refresh_token_expires_in": 600000, "token_expires_in": 7200 }

---

5. Refresh Access Token

Refresh an expired access token using the refresh token.

Endpoint: POST /oauth/token Authentication: None required

5.1 Query Parameters

Parameter	Type	Required	Description
grant_type	string	✅	Must be "refresh_token"
redirect_uri	string	✅	Must match a registered redirect URI
client_id	string	✅	Your OAuth client ID
refresh_token	string	✅	Refresh token from previous token response

5.2 Refresh Token Response

Success Response: 200 OK

Same response format as Get Access Token. The refresh token may be rotated (changed) in the response.

5.3 Examples

CURL Request

curl -X POST "https://api.firework.com/oauth/token?grant_type=refresh_token&redirect_uri=https://your-app.com/oauth_callback&client_id={CLIENT_ID}&refresh_token={REFRESH_TOKEN}"

---

6. Using Access Tokens

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

Authorization: Bearer {ACCESS_TOKEN}

6.1 Example API Request

curl -X POST "https://api.firework.com/api/v1/videos" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: multipart/form-data" \ -F 'metadata={"channel_id":"X6Xqd6W","caption":"My Video"}' \ -F "[email protected]"