Logo

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.

// Example: Connect to a user's authorized LIVE stream
const response = await fetch('https://tiktok.eulerstream.com/webcast/fetch', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    unique_id: 'streamer_username',
  }),
});

Use cases:

  • Building LIVE chat overlays
  • Creating real-time gift alerts
  • Tracking viewer engagement
  • Moderating LIVE streams

webcast:live_check

Check LIVE status

Check if multiple TikTok users are currently streaming LIVE.

// Example: Check if users are live
const response = await fetch('https://tiktok.eulerstream.com/webcast/bulk_live_check', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    unique_ids: ['user1', 'user2', 'user3'],
  }),
});
 
// Response: { "user1": true, "user2": false, "user3": true }

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.

// Example: Get hourly rankings
const response = await fetch('https://tiktok.eulerstream.com/webcast/rankings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    period: 'hourly',
    category: 'gaming',
  }),
});

Use cases:

  • Building leaderboard displays
  • Tracking trending creators
  • Competitive analytics

webcast:earnings

View earnings data

Access LIVE streaming earnings and gift statistics.

// Example: Get user earnings data
const response = await fetch('https://tiktok.eulerstream.com/webcast/user_earnings', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    unique_id: 'streamer_username',
  }),
});

Use cases:

  • Creator analytics dashboards
  • Revenue tracking
  • Gift statistics

webcast:sign_url

Generate signed URLs

Create authenticated URLs for TikTok API requests.

// Example: Sign a URL
const response = await fetch('https://tiktok.eulerstream.com/webcast/sign_url', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://www.tiktok.com/api/...',
  }),
});

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.

// Example: Send a chat message
const response = await fetch('https://tiktok.eulerstream.com/webcast/chat', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
    message: 'Hello from my app!',
  }),
});

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.

// Example: Mute a viewer
const response = await fetch('https://tiktok.eulerstream.com/webcast/room/mute', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
    user_id: '1234567890',
  }),
});
 
// Example: List muted viewers
const mutedList = await fetch('https://tiktok.eulerstream.com/webcast/room/muted', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
  }),
});

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.

// Example: Ban a viewer
const response = await fetch('https://tiktok.eulerstream.com/webcast/room/ban', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
    user_id: '1234567890',
  }),
});
 
// Example: List banned viewers
const bannedList = await fetch('https://tiktok.eulerstream.com/webcast/room/banned', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
  }),
});

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.

// Example: Disable comments
const response = await fetch('https://tiktok.eulerstream.com/webcast/room/comments', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
    enabled: false,
  }),
});

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.

// Example: Add a moderator
const response = await fetch('https://tiktok.eulerstream.com/webcast/room/moderator', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
    user_id: '1234567890',
  }),
});
 
// Example: List moderators
const modList = await fetch('https://tiktok.eulerstream.com/webcast/room/moderators', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
  }),
});

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.

// Example: Get live analytics
const response = await fetch('https://tiktok.eulerstream.com/webcast/room/analytics', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    room_id: '7123456789',
  }),
});

Use cases:

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

Requesting Scopes

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

const scopes = [
  'webcast:fetch',
  'webcast: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=One%20or%20more%20requested%20scopes%20are%20invalid

Checking Granted Scopes

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

interface TokenResponse {
  access_token: string;
  refresh_token: string;
  token_type: 'Bearer';
  expires_in: number;
  scope: string; // Space-separated granted scopes
}
 
// After token exchange
const tokens = await exchangeCodeForTokens(code);
const grantedScopes = tokens.scope.split(' ');
 
if (!grantedScopes.includes('webcast:fetch')) {
  // Handle missing required scope
  throw new Error('Required scope not granted');
}

Scope Reference Table

ScopePermissionTypical Use Case
webcast:fetchConnect to LIVE streamsChat overlays, gift alerts
webcast:live_checkCheck LIVE statusNotifications, dashboards
webcast:rankingsView rankingsLeaderboards, analytics
webcast:earningsView earningsCreator analytics
webcast:sign_urlGenerate signed URLsAdvanced integrations
webcast:chatSend chat messagesChat bots, automated responses
webcast:muteMute/unmute viewersStream moderation
webcast:banBan/unban viewersStream moderation
webcast:commentsToggle commentsStream management
webcast:moderatorsManage moderatorsStream management
webcast:live_analyticsView live analyticsReal-time dashboards

Best Practices

  1. Request minimum scopes: Only ask for what you need. Users trust apps that request fewer permissions.

  2. Explain why: In your app's UI, explain why you need each permission before starting the OAuth flow.

  3. Handle denied scopes: Users might not approve all requested scopes in future versions. Design your app to gracefully degrade.

  4. 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 FlowToken Lifecycle