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

The following scopes can be requested when a user authorizes your application:

attributes:edit
command:edit
play-history:edit
queue:edit
reward:edit
reward:read
song:edit
song-request:edit
song-request:read
streamer:edit
user:edit
user:read

Getting Tokens

The domain dedicated to authentication is

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)	comma 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:edit,queue:edit"

/* 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:edit,queue:edit',
);

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/authorize\
    ?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:edit", "queue:edit"],
  "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"

import fetch from 'fetch';

const response = await fetch('https://id.streamersonglist.com/oauth2/token', {
  method: 'POST',
  body: new URLSearchParams({
    scope: '',
    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": [],
  "token_type": "Bearer"
}