Adding your app to a channel

Your app can only see or act on a channel after that channel's creator adds it. The creator picks from the scopes your link asks for, and can take them away again at any time.

Send creators to:

https://thexive.com/developers/authorize?client_id=CLIENT_ID&scope=chat:read+chat:write
  • client_id is your app's public client id (from your app's page, or GET /api/apps/@me).
  • scope lists the scopes you need, separated by spaces or + (commas also work). Unknown scopes are ignored; a link with no valid scope is refused.
  • redirect_uri (optional) must exactly match one of the OAuth redirect URLs registered on your app. After approving, the creator is sent there with channel_id and the granted scope; if they cancel, with error=access_denied. A link with an unregistered redirect_uri is refused.
  • state (optional) is passed back to your redirect_uri unchanged. Use a random value and check it, to tie the callback to the person who started it.

The creator signs in, sees your app's name, icon and description with the permissions you asked for, and approves. Your app is then on their channel.

Changing scopes: opening the link again re-grants the app with the new scope set, replacing the old one. To add events:read later, send a link that lists every scope you still need, not just the new one.

Scopes

ScopeThe creator seesLets your app
chat:read Read your chat Read recent messages, and receive channel.chat.message, channel.chat.message_delete, channel.ban and channel.unban on EventSub.
chat:write Send messages in your chat as the bot Post in chat under your app's name and icon with a BOT badge.
chat:moderate Delete messages, time out and ban, pin messages and change chat settings in your chat Delete a message, time out, ban and unban viewers (never the creator or the channel's moderators), pin messages and change chat settings.
events:read See follows, gifts, subs, raids, Sparks and redemptions on your channel, and your subscriber count Receive the channel's activity (follows, subs, raids, redemptions …) and stream.online / stream.offline / channel.update on EventSub, catch up on missed activity, and read the subscriber total.
channel:manage Change your stream title and category, start raids and manage your VIPs Set the title and category, raid another live channel, and manage VIPs. See Stream & raids.
redemptions:manage See your channel-point rewards and redemptions, complete or refund them, and drop chests Read rewards and the redemption queue, accept / complete / reject redemptions, drop community chests. See Channel points.
commands:manage Create, edit and remove your chat commands List, create, edit and retire the channel's !commands. See Chat commands.
polls:manage Run polls and channel-point predictions in your chat Start, end and resolve polls and predictions. Predictions use channel points only.
panels:manage Add and update its own panel on your channel page Publish a data panel (text, image, links, a stats list) that Xive renders on the channel page.

Ask for the fewest scopes your app needs. A call that needs a scope the creator did not grant gets 403 with a missing_scope field.

List your channels

GET /api/apps/@me/channels lists every channel your app is on, with the scopes each creator granted.

curl https://api.thexive.com/api/apps/@me/channels \
  -H "Authorization: Bearer $XIVE_APP_SECRET"
{
  "success": true,
  "channels": [
    {
      "channel_id": "3e0b8a51-2f4c-4f8e-9a6d-1b7c5e2d9f04",
      "username": "nightowl",
      "display_name": "Night Owl",
      "scopes": ["chat:read", "chat:write"],
      "stream_id": "c71d0f2a-8b3e-4a19-b5d6-0e4f9a2c7b18",
      "is_live": true,
      "added_at": "2026-10-11T12:00:00Z"
    }
  ]
}
FieldMeaning
channel_idThe creator's profile id. This is the {channelId} in every /api/apps/channels/… URL and the channel_id on gateway events.
username, display_nameThe creator's handle and display name.
scopesWhat the creator granted.
stream_idThe channel's chat room: the live stream if there is one, else the most recent. null if the creator has never streamed.
is_liveWhether the channel is live right now.
added_atWhen the app was first added.

Removal

A creator can remove your app from their channel at any time. It stops at once: the channel drops out of /api/apps/@me/channels, its events stop reaching your gateway, and calls for it get 403. Treat a 403 with missing_scope as "this creator no longer wants this" and stop calling for that channel. Don't ask creators to re-add an app they removed.

Public and private apps

A new app is public: any creator can add it with your link. Switch it to private on its Console page while you're building — then only you can add it, and only to your own channel. Anyone else opening the link is told the app is private.

App names show in chat beside every message, so names that read as Xive or as channel staff (for example "Xive", "Official", "Moderator", "Admin", "Support") are refused, including look-alike spellings.