Authentication

StreamerSonglist provides an OAuth based authentication mechanism adhering to parts of the OAuth2.0 protocol

Tokens

Type	Description
User access tokens	Authenticate users and allow your app to make requests on their behalf. If your application uses StreamerSonglist for login or makes requests in the context of an authenticated user, you need to generate a user access token.
App access tokens	App access tokens are meant only for server-to-server API requests and should never be included in client code.

Clients

Type	Description	Token Type	Flow(s) Supported
OAuth	You need to use the authorization code flow to obtain access to a user's data based on scopes provided. Currently the app access token retrieved with the client credentials flow does not provide any additional non-public data for a user or streamer	User access token, App access token	Authorization code, client credentials
User	You want to create an application based on your own access to data. This provides identical authorization to the token used when using the streamersonglist.com website.	App access token	Client credentials
Streamer	You want to create an application that can access all data to a specific streamer	App access token	Client credentials

Scopes

Scopes use a 3-segment dot-separated format: category.resource.permission

For example, streamer.song.r grants Read access to the Songs resource in the streamer category.

Permissions (CRUDS)

Each resource supports the following permissions:

Code	Permission
c	Create
r	Read
u	Update
d	Delete
s	Search

Available Resources

Resource	Label	Wildcard Scope
streamer.action-log	Activity Log	streamer.action-log.*
streamer.attribute	Attributes	streamer.attribute.*
streamer.command	Commands	streamer.command.*
streamer.integration	Integrations	streamer.integration.*
streamer.overlay	Overlays	streamer.overlay.*
streamer.play-history	Play History	streamer.play-history.*
streamer.queue	Queue	streamer.queue.*
streamer.setting	Settings	streamer.setting.*
streamer.song	Songs	streamer.song.*
user.preference	Preferences	user.preference.*
user.song-request	Song Requests	user.song-request.*

Wildcard Matching

You can request all permissions for a resource using the wildcard * as the permission segment.

For example, streamer.song.* grants all permissions (create, read, update, delete, search) for songs.

Wildcard matching follows fosite's WildcardScopeStrategy. A * in any segment matches any value in that position:

• streamer.song.* matches streamer.song.r, streamer.song.c, etc.
• streamer.song.r matches only streamer.song.r

When requesting scopes for your application, use the wildcard form (resource.*) to request full access or individual permission codes for fine-grained control.

Getting Tokens

The domain dedicated to authentication is https://id.staging.streamersonglist.com/oauth2

Supported authentication flows:

Flow Type	Description	Token Type
Authorization code		User access tokens
Client credentials		App access tokens

Authorization Code Flow

GET /oauth2/authorize

Parameter	Type	Description
client_id	string (required)	id generated from registered client
redirect_uri	URI (required)	callback uri specified when registering the client
response_type	string (required)	Only allowed value is code
scope	string (required)	space separated list of scopes
state	string (optional)	Your unique token, generated by your application. This is an OAuth 2.0 opaque value, used to avoid CSRF attacks. This value is echoed back in the response. It's strongly recommended to provide this.
nonce	string (optional)	is a random value generated by your app that enables replay protection when present

curl "https://id.streamersonglist.com/oauth2/authorize\
    ?client_id=<your_registered_client_id>\
    &redirect_uri=<your_registered_redirect_uri>\
    &response_type=code\
    &state=bQxc3kvjuzTmwX4JE9rb7HvkvoUTG6\
    &scope=streamer.song.* streamer.queue.*"

/* web client */
import fetch from 'fetch';
const response = await fetch(
  'https://id.streamersonglist.com/oauth2/authorize?\
    client_id=<your_registered_client_id>\
    &redirect_uri=<your_registered_redirect_uri>\
    &response_type=code\
    &state=bQxc3kvjuzTmwX4JE9rb7HvkvoUTG6\
    &scope=streamer.song.* streamer.queue.*',
);

The above request returns a 302 redirect to your provided redirect_uri with a code query parameter attached, the code value is needed for the next step

/* your server */
app.get('auth/callback', (req, res) => {
  const code = req.query.code;
});

Exchange for Token

POST /oauth2/token

Parameter	Type	Description
client_id	string (required)	id generated from registered client
client_secret	string (required)	secret generated from registered client
redirect_uri	URI (required)	callback uri specified when registering the client
grant_type	string (required)	For this flow, only authorization_code is allowed
code	string (required)	code value returned from the previous request (/authorize)

curl "https://id.streamersonglist.com/oauth2/token\
    ?client_id=<your_client_id>\
    &client_secret=<your_client_secret>\
    &redirect_uri=<your_registered_callback_uri>\
    &grant_type=authorization_code\
    &code=<code_from_callback_query_param>"

import fetch from 'fetch';

const response = await fetch('https://id.streamersonglist.com/oauth2/token', {
  method: 'POST',
  body: new URLSearchParams({
    code: '<code from previous authorize callback>',
    client_id: `<your registered client's id>`,
    client_secret: `<your registered client's secret>`,
    grant_type: 'authorization_code',
    redirect_uri: `your registered client's redirect uri`,
  }),
});

const data = await response.json();
const accessToken = data.access_token;

Example of the full json response above:

{
  "access_token": "eyJhbG...adQssw5c",
  "refresh_token": "eyJhbG...gdJpx3wCc",
  "expires_in": 3600,
  "scope": "streamer.song.* streamer.queue.*",
  "token_type": "Bearer"
}

Client Credentials Flow

POST /oauth2/token

Parameter	Type	Description
client_id	string (required)	id generated from registered client
client_secret	string (required)	secret generated from registered client
grant_type	string (required)	For this flow, only client_credentials is allowed
scope	string (required)

curl "https://id.streamersonglist.com/oauth2/token\
    ?client_id=<your_client_id>\
    &client_secret=<your_client_secret>\
    &grant_type=client_credentials\
    &scope=streamer.song.r streamer.queue.r"

import fetch from 'fetch';

const response = await fetch('https://id.streamersonglist.com/oauth2/token', {
  method: 'POST',
  body: new URLSearchParams({
    scope: 'streamer.song.r streamer.queue.r',
    client_id: `<your registered client's id>`,
    client_secret: `<your registered client's secret>`,
    grant_type: 'client_credentials',
  }),
});

const data = await response.json();
const accessToken = data.access_token;

Example of the full json response above:

{
  "access_token": "eyJhbG...adQssw5c",
  "refresh_token": "eyJhbG...gdJpx3wCc",
  "expires_in": 3600,
  "scope": "streamer.song.r streamer.queue.r",
  "token_type": "Bearer"
}

Streamer Access Tokens

Streamer access tokens are simple, database-backed tokens that grant full access to a specific streamer's data. Unlike OAuth tokens, they do not use scopes — a valid streamer token has full read and write access to that streamer's resources.

Streamer tokens are ideal when you are building a personal integration for your own channel and don't need the complexity of the OAuth flow.

You can create and manage streamer access tokens from your Settings > Access page on streamersonglist.com.

Authorization Header

Include the token in the Authorization header with the Streamer prefix:

Authorization: Streamer <token>

Examples

curl -H "Authorization: Streamer <your_token>" \
  "https://api.streamersonglist.com/v2/streamers/<streamer_id>/songs"

const response = await fetch('https://api.streamersonglist.com/v2/streamers/<streamer_id>/songs', {
  headers: {
    Authorization: 'Streamer <your_token>',
  },
});

const data = await response.json();

Differences from OAuth Tokens

Feature	Streamer Access Token	OAuth Token
Setup	Create from settings page	Register an OAuth client
Scopes	Full access (no scopes)	Fine-grained scopes
Token format	Authorization: Streamer <tok>	Authorization: Bearer <tok>
Best for	Personal / single-streamer use	Third-party apps, multi-user apps