Authentication

Create an API key, send it as a bearer token, and pick the scopes it carries.

Create an API key in Dashboard -> Settings -> Developer (owner and super admins only). The key is shown once at creation - store it somewhere safe. You can rotate a key from the same page at any time: it keeps its name and scopes but gets a brand-new key, shown once, and the old key stops working immediately. Rotation is deliberately dashboard-only - a key can’t mint its own replacement through the API. Send the key as a bearer token on every request:

curl https://api.tippage.com/v1/me \
  -H "Authorization: Bearer tp_live_..."

The key identifies your TipPage, so there’s no account id in any URL. Keys are server-side credentials: never put one in a browser page, an overlay, or anything visible on stream.

Building an app for other streamers? Don’t ask them for keys - register an OAuth app and give them a Connect button. The access token works everywhere a key does, with the same scopes. See OAuth 2.0.

Scopes

Each key carries only the scopes you pick (editable later in the dashboard):

Scope	Grants
`tts:read`	The TTS queue and played history, messages and TTS audio URLs included
`tips:create`	Create tips TipPage didn’t take payment for. `source` labels where it came from (reports group by it); `paid: true` says money was really processed on that platform, so it counts as revenue. Neither = a manual tip, same as the dashboard’s manual-tip form
`tts:control`	Pause, resume, skip, clear, remove, replay, and drive playback (start/finish) of the TTS queue
`media:read`	The media queue, played-media history, and live playback status
`media:control`	Pause, resume, and skip the media queue, queue videos directly, and show/hide the player on the overlay
`tipping:control`	Open and close tipping. Closing stops new checkouts; viewers already mid-payment still complete
`viewers:read`	Viewers who signed in to the tip page: first sign-in dates, sub tiers, sub-reward credit balances, and past sub-reward messages
`viewers:manage`	Grant and revoke sub-reward credits for signed-in viewers
`channel_points:manage`	Resolve channel point redemptions of TipPage-managed rewards - fulfill (keep the points) or cancel (refund the points)
`webhooks:manage`	Manage webhook endpoints via the API
`timers:manage`	Create, update, enable/disable, and delete the chat bot’s scheduled messages (timers)
`counters:manage`	Create, read, set, increment, and delete chat counters - API writes update overlay labels live, exactly like a chat `{count}` bump
`chat:write`	Send messages to the streamer’s Twitch chat, spoken by their bot
`commands:manage`	Create, update, enable/disable, and delete the chat bot’s custom `!commands`
`overlays:manage`	List and delete overlays (never their keys), reload a connected overlay’s browser source, fire the Event celebration widget on demand (all overlays, one overlay, or one specific widget), and read/update/add-to each overlay’s tip goal
`ai_voices:manage`	AI voices (closed beta): read the voice catalog and this month’s usage, toggle the feature or individual voices

Keys deliberately can’t touch payments, settings, or team management. Two reads need no scope at all - any valid key can check the tipping status and the leaderboard, since both are visible on the public tip page anyway.