Connect with ForgeCast

API keys are for your own account. To build something other streamers use (a dashboard, a bot, an overlay service), use Connect with ForgeCast: it's standard OAuth 2.0 with PKCE, so any OAuth library works.

1. Your app sends the streamer to ForgeCast's Allow screen.
2. They sign in (if they aren't already), see your app and what it asks for, and press Allow.
3. ForgeCast sends them back to your app with a one-time code.
4. Your app swaps the code for an access token (1 hour) and a refresh token (60 days, a new one each time).
5. You call the API with the access token, like an API key. It can do only what the streamer allowed, within their plan.

Streamers can disconnect your app at any time in Account → Connections; its tokens stop working at once.

Register your appCopy Anchor Link

In Account → Developer, under Your apps, press New app and give it:

• a name (it can't contain "ForgeCast"), a short description and, if you like, a homepage and a square logo (https);
• its redirect addresses: exactly where ForgeCast may send people back. https, http only on 127.0.0.1 or localhost (for desktop apps and testing), or your app's own scheme (myapp://callback);
• the scopes it may ask for (the same as API key scopes);
• My app has a server: it gets a client secret to keep on that server. Leave it off for a desktop or mobile app, which can't keep a secret: it signs in with PKCE alone.

You get a client ID (fcapp_…), and the secret once. Apps start unverified: the Allow screen tells streamers ForgeCast hasn't checked them. Write to us to have yours checked; a verified app shows a badge.

Discovery for OAuth libraries: https://forgecast.in/.well-known/oauth-authorization-server

1. Send the streamer to the Allow screenCopy Anchor Link

They come back to your redirect_uri with ?code=…&state=…, or ?error=access_denied&state=… if they pressed Cancel. Other problems come back as error=invalid_scope or error=invalid_request with an error_description. A wrong client_id or redirect_uri sends nobody anywhere: the page shows the problem instead.

2. Swap the code for tokensCopy Anchor Link

The code works once, for 60 seconds.

curl -s "$FORGECAST_URL/api/oauth/token" \
  -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=authorization_code \
  -d code="$CODE" \
  -d code_verifier="$CODE_VERIFIER" \
  -d redirect_uri="https://yourapp.example/callback"

Send the app's credentials as HTTP Basic (client_id:client_secret) or as client_id and client_secret fields. Errors are standard OAuth: { "error": "invalid_grant", "error_description": "…" }.

3. Call the APICopy Anchor Link

Send the access token like an API key:

curl -s "$FORGECAST_URL/api/v1/me" -H "Authorization: Bearer $ACCESS_TOKEN"

• It can do only what the streamer allowed: anything else is 403 insufficient_scope. Their plan still applies to everything.
• Each app has its own rate limit per streamer: their plan's requests a minute (10, or 60 on Ultimate).
• Some endpoints (managing keys, teams, cloud sync) are for the streamer themselves: apps get 403 there.
• Call the API from your server or app, not from a web page: the API doesn't send cross-site (CORS) headers.

4. RefreshCopy Anchor Link

Before the access token runs out, swap the refresh token for new ones. Each refresh token works once: keep the new one. If a refresh token is ever used twice, ForgeCast assumes it leaked and ends the streamer's connection.

curl -s "$FORGECAST_URL/api/oauth/token" -u "$CLIENT_ID:$CLIENT_SECRET" \
  -d grant_type=refresh_token -d refresh_token="$REFRESH_TOKEN"

DisconnectCopy Anchor Link

Send token=<refresh token> with your app's credentials when the streamer disconnects your app on your side. Their connection ends; the answer is always 200.

RulesCopy Anchor Link

Read the Developer Terms before you launch: use only what streamers allowed, for what you told them; keep their data safe and delete it when they disconnect; don't use ForgeCast in your app's name. Charging for your app is fine.