Reference

OAuth scopes

A scope is one line on the consent screen a streamer reads before they trust you. Ask for the four your app needs and most people say yes; ask for everything and they read the list twice and close the tab. Below: the scope sets for the four apps people usually build, then the full registry, then the two rules that decide whether a scope is granted automatically or waits on a human.

This page reads the live scope registry from api.velora.tv/api/developer/oauth/scopes. If that call fails it falls back to a copy compiled into this page, which may lag the server.

Start from what you are building

These are the scope sets the four common kinds of Velora app request. They are a starting point, not a ceiling — trim anything your app does not call.

Streaming software (OBS, Meld Studio)

For apps that need to configure and start streams on behalf of the user.

stream:keystream:readstream:writeuser:read

Chat bot (Streamer.bot, Firebot)

For apps that read and respond to chat messages.

chat:readchat:writeuser:readchannel:points:read

Analytics dashboard

For apps that display viewer stats, followers, and subscriber information.

user:readstream:readfollowers:readsubscriptions:read

Moderation tool

For apps that help moderate chat and manage channel settings.

chat:readchat:moderatechannel:readuser:read

Requesting scopes

Request scopes by including them in your authorization URL, separated by spaces:

Authorization URL
https://velora.tv/oauth/authorize?
  client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/callback
  &response_type=code
  &scope=user:read stream:read chat:write
  &state=RANDOM_STATE
  &code_challenge=YOUR_CODE_CHALLENGE
  &code_challenge_method=S256

How a scope is granted

Every scope in the registry is one of two kinds. Read this before the table below, because it is what the Status column means.

Auto-granted scopesAuto

Granted automatically when user authorizes.

Approval requiredApproval

May require admin approval for your app.

Staff reviewedSensitive

Scopes the registry marks sensitive are staff-gated and never auto-granted. Plan for the review rather than discovering it when a request stalls.

Every scope

The complete registry, grouped by category. Where a scope carries a rate limit it is printed beside the name as requests per window.

Loading scopes…

Best practices

1.
Request minimum necessary scopes

Only request the scopes your application actually needs. Users are more likely to trust and authorize apps with fewer permissions.

2.
Explain why you need each scope

In your app's description and during authorization, clearly explain what each permission is used for.

3.
Use incremental authorization

Request basic scopes initially, then request additional scopes when features that need them are accessed.

4.
Handle scope denial gracefully

Users can deny specific scopes. Your app should handle reduced permissions without crashing.

Next steps