# 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`: ```bash 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](https://gumball.fm/user/settings/api-activity). ## Manage keys You create, view, and revoke keys in the **API Keys** box on [Account Settings](https://gumball.fm/user/settings#api-keys). - 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](https://gumball.fm/developers/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](https://gumball.fm/developers/connect-an-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](https://gumball.fm/user/settings#connected-apps). 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](https://gumball.fm/developers/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.