Authentication
Two ways to authenticate
Every request to the API and the MCP server carries a credential. Your own code sends an API key. An AI agent can send a key too, or sign in: you approve the agent on gumball.fm and never handle a key. See Sign in from an AI agent below.
Send a key
Send the key in the Authorization header of every request, after the word Bearer:
curl https://api.gumball.fm/v1/me \
-H "Authorization: Bearer gum_YOUR_KEY"A key starts with gum_. Send it only to https://api.gumball.fm, and only in the Authorization header: never in a URL.
What a key can reach
A key acts as the account that created it. It reaches what that account reaches on gumball.fm and nothing else: an advertiser's key reads shows and the campaigns the advertiser is on the team of, and a creator's key reads the shows the creator is a member of.
A record the account can't reach answers not_found, the same as a record that doesn't exist.
Access levels
You choose a key's access level when you create it:
| Access level | What the key can do |
|---|---|
| Read-only | Read data. |
| Read and write | Read data and change it: build a campaign, reserve ad slots, or manage a show's schedule. |
A read-only key that calls an operation that changes data gets the forbidden error. Choose read-only unless you need those operations. Every change a key or connected app makes is listed on API Activity.
Manage keys
You create, view, and revoke keys in the API Keys box on Account Settings.
- Gumball shows a key once, when you create it. If you lose it, revoke it and create another.
- An account holds up to 10 keys at a time.
- A key expires after 30 days, 90 days, or one year, or never, as you choose. The default is one year.
- Revoking a key stops it at once.
- Gumball emails you when a key is created on your account.
When a key stops working
Gumball checks the key and the account on every request. A request is refused when any of these is true:
| Situation | Status | Error code |
|---|---|---|
| The header is missing, malformed, or names no key | 401 |
unauthenticated |
| The key was revoked | 401 |
key_revoked |
| The key expired | 401 |
key_expired |
| The account is disabled | 403 |
account_disabled |
| The account isn't approved yet | 403 |
account_not_approved |
| The account hasn't accepted the current terms of service on gumball.fm | 403 |
terms_not_accepted |
| The account type can't use the operation | 403 |
forbidden |
For the error format, see Errors.
Sign in from an AI agent
An AI client that supports MCP sign-in connects without a key:
- You add the Gumball MCP server to the client. See Connect an AI agent.
- The client sends you to gumball.fm. Log in if you aren't already.
- Gumball shows the app's name and where it comes from, and you choose Read-only or Read and write. Read-only is selected for you.
- Click Approve. Gumball emails you that an app was connected.
What to know about a connection:
- It acts as you, with the access level you chose, like a key with that level.
- It ends by itself 30 days after you approve it. Connect again to keep using the agent.
- You see every connection, and disconnect one, under Connected Apps on Account Settings. A disconnected app stops working at once.
- Changing or resetting your password disconnects every app and revokes every key.
- An app chooses its own name. Check where it comes from, and approve only a connection you started.
Only an approved advertiser or creator account can connect an app. The first time, Gumball asks you to accept the API terms.
Calls from a browser
The API accepts browser calls from gumball.fm only. A page on another website can't call it, so keep your key on a server.
Read this page as plain text.