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:

  1. You add the Gumball MCP server to the client. See Connect an AI agent.
  2. The client sends you to gumball.fm. Log in if you aren't already.
  3. 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.
  4. 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.