Authentication
API keys and their scopes, and the other two ways ForgeCast knows who is calling.
Who can call the API
| Caller | Signs in with | Good to know |
|---|---|---|
| Your scripts and servers | An API key: Authorization: Bearer fck_... | Limited to its scopes, and to 10 requests a minute per account |
| Apps for other streamers | An access token from Connect with ForgeCast | Limited to what the streamer allowed; its own rate limit per streamer |
| The website | A signed-in browser session | The only way to manage API keys and signed-in devices |
| Desktop apps | An access token from desktop app sign-in | Same access as the signed-in user, except managing API keys |
The rest of this page is about API keys, which is what you'll use.
Create an API key
Sign in to the website and open your account page.
Under Developer API keys, give the key a name, choose the permissions (scopes) it needs, pick an expiry, and click Create key.
Copy the key immediately. It starts with fck_ and is shown only once: ForgeCast stores just a hash and can't show it again. If you lose it, revoke it and make a new one.
Treat keys like passwords
Keep keys on your server or in a secrets manager, never in a web page, a mobile app, a public repository or a screenshot. A key acts as your account (within its scopes) until you revoke it. If one leaks, revoke it on your account page; it stops working immediately.
Using a key
Send it as a bearer token on every request:
GET /api/v1/inventory HTTP/1.1
Authorization: Bearer fck_your_key_hereAn Authorization header always means a program is calling: a bad key gets 401, and never falls back to anything else.
Scopes
A key can only do what its scopes allow. They're fixed when the key is created.
| Scope | Allows |
|---|---|
profile:read | GET /me |
catalog:read | Browse the predefined overlays |
sounds:read | Search and download sounds from the sound catalog |
inventory:read | List your inventory and read overlay documents |
inventory:write | Add and remove inventory items, create, update and fork overlays |
assets:read | List the pictures in your library (Pictures) |
assets:write | Upload and delete pictures in your library |
plugins:read | Browse the plugin marketplace, download plugins and see the ones you bought (Plugins) |
plugins:write | Publish new versions of your plugins, take them down and set their prices |
sales:read | Your plugin sales, earnings and payouts |
Calling an endpoint without the right scope returns 403 insufficient_scope, naming the scope you need. Scopes never override your plan: a key with inventory:write on a Free account still can't create overlays (403 plan_required).
Key rules
- Up to 5 active keys per account (revoked and expired keys don't count).
- Expiry is optional, 1 to 365 days. Expired keys stop working automatically.
- Names are 1 to 40 characters.
- Revoking is immediate and permanent.
Keys are listed, created and revoked only on the website (a signed-in browser session). The key endpoints reject API keys, so a leaked key can never be used to make more keys or to revoke yours.
Security
Found a vulnerability? Please report it privately rather than in public, and give us time to fix it.