🔒 Authentication

Linking user accounts across streaming platforms.

Orchdio supports some features that allow you manage a user's library for them depending on the platform you are targeting. In order to do this, Orchdio requires user authentication and authorization on the said platform.

Initiate user authentication

To authenticate a user, you need to make a request to the endpoint stated below. Depending on the platform you are trying to authenticate the user on, you must pass the scopes you want the user to authenticate your application on.

In order to complete the authentication flow, you must add a redirect URL in your music streaming platform app settings. This value is: https://api.orchdio.dev/v1/auth/{platform}/callback where platform is the key-value.

For example, the key for Spotify platform is spotify. You can find the key-value for all the supported platforms here.

When you create a new app and add your Deezer credentials, Orchdio generate a unique Deezer state for you. This 10 character token is needed in your redirect URL on Deezer as a query parameter state. You can always find this on your app's dashboard.

Scopes are values that specify the type of access your app has on the user's target platform. Each platform has different scopes you need to pass. At the moment, Orchdio requires you pass scopes when trying to integrate with Spotify and supports all available Deezer Scopes due to architectural constraints. Apple Music is also supported but do not require you pass scopes.

Go here to see the list of Spotify scopes and the access they have.

You can see the permissions available for Deezer here.

get

Returns the redirect URL for the platform in order to authenticate the user on the target platform

Path parameters

platformstring · enumRequired

The platform to connect to

Possible values:

Header parameters

x-orchdio-public-keystring · uuidRequired

The public key of the Orchdio server

Example: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11

Responses

200

The redirect URL for the platform in order to authenticate the user on the target platform

application/json

401

Unauthorized

application/json

500

Internal server error

application/json

get

HTTPcURLJavaScriptPython

GET /v1/{platform}/connect HTTP/1.1
Host: api.orchdio.dev
x-orchdio-public-key: a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11
Accept: */*

{
  "data": {
    "url": "https://accounts.spotify.com/authorize?client_id=1901737ea993417b98959fefb66c98be&redirect_uri=https%3A%2F%2Fweb-production-2629.up.railway.app%2Fapi%2Fv1%2Fspotify%2Fauth&response_type=code&scope=user-read-private+user-library-read+playlist-read-private+playlist-read-collaborative+user-follow-read+playlist-modify-private+playlist-modify-public+user-read-email&state=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2NzM1NjAyMjIsImlhdCI6MTY3MzU1OTYyMiwianRpIjoiMWZlODc2ZTItNjgzMS00OTFiLTk0NDAtYTM5NWZiYjg5OTIwIiwiYXBwX2lkIjoiOWNjMDM0NjQtY2YyOS00MDUwLWE1MjItYzI4NzJmMmE0MGFhIiwicmVkaXJlY3RfdXJsIjoiaHR0cHM6Ly96b292ZS54eXoiLCJwbGF0Zm9ybSI6InNwb3RpZnkiLCJhY3Rpb24iOnsicGF5bG9hZCI6bnVsbCwiYWN0aW9uIjoiYXBwX2F1dGgifX0.WWDwKmXMqZ8n039yTzgaQk0PxnM8Y_q3HozVGwlWTX0"
  },
  "message": "Redirect URL",
  "status": 200
}

The user would first be presented with a screen that explains your app and what it needs to do. The user would then be redirected to the main authentication flow of the streaming platform and finally, to the redirect url specified in your app.

In the redirect_url, a token query string is added which contains a JWT that can be decoded in order to extract the user's information including the Orchdio ID (uuid) . The ID would be needed in future user related requests. It also contains a field that specifies the platform the user just authenticated.

The decoded JWT looks like:

// Some code
{
  "exp": 1680533202,
  "iat": 1680490002,
  "email": "[e-mail]",
  "username": "nerodrome",
  "uuid": "fd02e2ea-6f4c-11ed-aa88-abcd1390359d",
  "platform": "spotify"
}