OAuth Integration

OAuth Scopes

Available OAuth scopes and what permissions they grant to your application.

OAuth scopes define what actions your application can perform on behalf of the user. Request only the scopes your application actually needs — users are more likely to approve applications that request minimal permissions.

Available Scopes

webcast:fetch

Access LIVE streams

Connect to TikTok LIVE streams and receive real-time events like comments, gifts, and viewers.

Use cases:

Building LIVE chat overlays
Creating real-time gift alerts
Tracking viewer engagement
Stream moderation tools

webcast:bulk_live_check

Check LIVE status

Check if multiple TikTok users are currently streaming LIVE.

Use cases:

Building "who's live" dashboards
Sending notifications when favorites go live
Monitoring multiple creators

webcast:rankings

View LIVE rankings

Access hourly and daily LIVE streaming rankings and leaderboards.

Use cases:

Building leaderboard displays
Tracking trending creators
Competitive analytics

webcast:user_earnings

View earnings data

Access LIVE streaming earnings and gift statistics.

Use cases:

Creator analytics dashboards
Revenue tracking
Gift statistics

webcast:sign_url

Generate signed URLs

Create authenticated URLs for TikTok API requests.

Use cases:

Advanced API integrations
Custom TikTok API calls
Building custom tools

webcast:chat

Send chat messages

Send chat messages to TikTok LIVE rooms on behalf of the user.

Use cases:

Chat bots and automated responses
Moderation tools
Interactive stream features
Viewer engagement automation

webcast:mute

Mute viewers

Mute, unmute, and list muted viewers in TikTok LIVE streams.

Use cases:

Stream moderation tools
Automated spam prevention
Managing disruptive viewers

webcast:ban

Ban viewers

Ban, unban, and list banned viewers from TikTok LIVE streams.

Use cases:

Stream moderation dashboards
Automated ban management
Maintaining ban lists across streams

webcast:comments

Toggle comments

Enable or disable comments in TikTok LIVE streams.

Use cases:

Stream management tools
Temporarily pausing chat during important moments
Automated comment control based on conditions

webcast:moderators

Manage moderators

Add, remove, and list moderators for TikTok LIVE streams.

Use cases:

Stream management dashboards
Automated moderator assignment
Multi-stream moderator management

webcast:live_analytics

View live analytics

Access real-time analytics data for TikTok LIVE streams.

Use cases:

Real-time stream dashboards
Viewer engagement tracking
Performance monitoring during streams

webcast:sensitive_words

Manage sensitive words

Add, remove, and list sensitive words for TikTok LIVE streams.

Use cases:

Content moderation
Automated word filtering
Stream safety management

user:info

View account info

Access basic account information such as username and avatar.

Use cases:

Displaying user profile information
Account identification

Making Authenticated Requests

All OAuth-authenticated API requests use the x-oauth-token header:

const response = await fetch('https://tiktok.eulerstream.com/webcast/fetch', {
  method: 'POST',
  headers: {
    'x-oauth-token': accessToken,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    unique_id: 'streamer_username',
  }),
});

The x-oauth-token header is mutually exclusive with the x-cookie-header used for API key authentication. Do not send both in the same request.

Requesting Scopes

When initiating the OAuth flow, specify scopes as a space-separated string:

const scopes = [
  'webcast:fetch',
  'webcast:bulk_live_check',
].join(' ');

const authUrl = new URL('https://www.eulerstream.com/tiktok/oauth/authorize');
authUrl.searchParams.set('client_id', clientId);
authUrl.searchParams.set('redirect_uri', redirectUri);
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('scope', scopes);

Scope Validation

If you request invalid scopes, the authorization will fail with an invalid_scope error:

https://yourapp.com/callback?error=invalid_scope&error_description=Invalid%20scopes%3A%20webcast%3Ainvalid

If your OAuth client has a restricted set of supported_scopes configured, requesting a scope outside that set will also fail.

Checking Granted Scopes

The token response includes the granted scopes as an array. Always verify these match your expectations:

const result = await exchangeCodeForTokens(code);
const grantedScopes = result.scopes; // string[]

if (!grantedScopes.includes('webcast:fetch')) {
  // Handle missing required scope
  throw new Error('Required scope not granted');
}

Scope Reference Table

Scope	Permission	Typical Use Case
`webcast:fetch`	Connect to LIVE streams	Chat overlays, gift alerts
`webcast:bulk_live_check`	Check LIVE status	Notifications, dashboards
`webcast:rankings`	View rankings	Leaderboards, analytics
`webcast:user_earnings`	View earnings	Creator analytics
`webcast:sign_url`	Generate signed URLs	Advanced integrations
`webcast:chat`	Send chat messages	Chat bots, automated responses
`webcast:mute`	Mute/unmute viewers	Stream moderation
`webcast:ban`	Ban/unban viewers	Stream moderation
`webcast:comments`	Toggle comments	Stream management
`webcast:moderators`	Manage moderators	Stream management
`webcast:live_analytics`	View live analytics	Real-time dashboards
`webcast:sensitive_words`	Manage sensitive words	Content moderation
`user:info`	View account info	Profile display

Best Practices

Request minimum scopes: Only ask for what you need. Users trust apps that request fewer permissions.
Explain why: In your app's UI, explain why you need each permission before starting the OAuth flow.
Re-request when needed: If you add new features requiring additional scopes, request them incrementally rather than upfront.

Scope Limitations

Scopes are granted per-authorization. If you need additional scopes later, users must re-authorize.
Refresh tokens maintain the same scopes as the original authorization — you cannot expand scopes via refresh.
Some scopes may have additional rate limits or usage restrictions.

Authorization Flow Token Lifecycle