Authentication and scopes

Every request to the Developer API carries a token in the Authorization header. For a creator's own tools and scripts, that is a personal access token:

Authorization: Bearer gleem_pat_k3j9x0q2m1ab_Zx8…

Tokens belong to one creator account and only ever see that account's data.

Building a tool for other creators? Register it as an OAuth app instead, so creators connect it by clicking Allow rather than pasting a token. OAuth access tokens (gleem_oat_…) go in the same header and work with every endpoint on this page.

Creating and revoking tokens

Tokens are created and revoked on the Developer page of your dashboard.

• The full token is shown once, when it is created. Gleem keeps only a hash of it, so it cannot be shown again. If it is lost, create a new one.
• A token can expire after 30, 90 or 365 days, or never.
• Revoking a token takes effect on the very next request, including an open WebSocket's next channel authorisation.
• The page shows when each token was last used, to the minute.

Every token starts with gleem_pat_, so a leaked one is easy to recognise in a log or a public repository.

Tokens and webhooks are covered by the Developer Terms.

Scopes

A token can only do what its scopes allow. Give each tool its own token with only the scopes it needs. A tool that only shows alerts does not need to be able to close your queue.

Scope	Allows
events:read	Receiving events over the WebSocket.
tips:read	Reading Gem messages and the leaderboard.
queue:read	Reading the Treat queue.
queue:write	Opening and closing the queue, moving entries along and refunding them.
treats:read	Reading your Treats.
treats:write	Showing, hiding and pinning Treats.
tickets:write	Granting Trigger Tickets.
members:read	Reading membership tiers and member counts.
irl:read	Reading your Gleem IRL devices and how their streams are doing.
irl:network	Sensitive. Your IRL devices' IP addresses, on top of irl:read. See Network addresses.
irl:write	Pairing, controlling and removing IRL devices, and registering a phone.
hosting:read	Reading your OBS rentals, including how to connect to their OBS.
hosting:write	Reserved for starting and ending OBS rentals. No endpoint needs it yet.
stream:read	Reading your stream on Twitch, its recent chat and activity, and the Quick Actions layout, and the Stream Manager channel.
stream:write	Chatting, deleting messages, timing out and banning, and changing the title and category, as you; saving the Quick Actions layout.
webhooks:write	Registering webhooks for the creator. OAuth apps only.

A request the token's scopes do not cover is refused with 403 and the code insufficient_scope. The error names the scope that was missing.

Some scopes also need a product on the account. irl:read, irl:network, irl:write, stream:read and stream:write belong to the Gleem IRL beta, and hosting:read to OBS Server Hosting; without it the request is refused with 403 and the code feature_unavailable. The stream scopes act on Twitch with your own Twitch connection, which gets the permissions for that once, when you reconnect Twitch for the Stream Manager; signing in to gleem.gg with Twitch never asks for them. Until then the Stream Manager names what is missing and where to reconnect (missing_scopes and reconnect_url, see Stream Manager).

GET /api/v1/me

Needs no scope. Use it to check a token and to find the event stream:

{
    "creator": {
        "id": 12,
        "slug": "ghostzero",
        "display_name": "GhostZero",
        "twitch_id": "123456",
        "is_live": false,
        "url": "https://gleem.gg/ghostzero"
    },
    "token": {
        "name": "Streamer.bot",
        "scopes": ["events:read"],
        "expires_at": null
    },
    "websocket": {
        "url": "wss://gleem.gg/ws/app/<key>?protocol=7&client=gleem-api&version=1.0",
        "channel": "private-creator.12.events",
        "auth_url": "https://gleem.gg/api/v1/socket/auth"
    }
}

websocket is null when the token lacks events:read.

Called with an OAuth access token, the response also names your app, and token.name is the app's name:

{
    "app": { "id": "gla_7f3k2m9q", "name": "Chat Overlay" }
}

Called with an app token from the client credentials grant, the app object is the whole response.