Authentication

There are two ways for a user to interact with the Epidemic Sound Connect API:

1. Free Tracks Access

Authentication Flow: Partner authentication flow

Eligibility: All users of your application

Access: Users have access to a curated selection of free tracks.

2. Full Library Access

Authentication Flow: Connect authentication flow

Eligibility: Users who have connected their Epidemic Sound account

Access: Users with connected accounts gain access to the entire Epidemic Sound library, unlocking a comprehensive selection of tracks.

By selecting the appropriate authentication flow, you can tailor the user experience based on their account status, ensuring seamless integration and access to the desired level of content

Partner Authentication Flow

The partner authentication flow gives users access to a set of predefined tracks.

Step 1: Get a partner token

The initial step in interacting with the API is to authenticate as a Partner and receive a Partner Token. A Partner Token can be obtained by providing your accessKeyId and accessKeySecret in a request to the /partner-token endpoint. The Partner Token has a TTL (Time To Live) of 60 minutes, after which a new Partner Token needs to be requested.

Step 2: Get a user token

After a Partner Token has been received, your app will need to request a User Token per unique user interacting with your app. The User Token also has a TTL of 60 minutes. To get a User Token, send a request containing a userId (your unique userId to identify your unique end user) to the /token endpoint. The response of this request will contain the User Token. This User Token will be used in subsequent requests to the API.

Note you will need to supply the Partner Token in the Authorization header of the request.

Example request

curl -X 'POST' 'https://partner-content-api.epidemicsound.com/v0/token' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer {your-partner-token-value}' \
  -H 'Content-Type: application/json' \
  -d '{ "userId": "e95cc657-adaa-4514-96f8-ce3df57dad0b" }'

caution

You can use any random string for userId. For GDPR compliance, please use a userId suitable to expose to third parties.

Connect Authentication Flow

Epidemic Sound Connect API uses OAuth 2.0 to allow developers to get a user access token to access the full library of 40 000 tracks as well as personalised content such as liked tracks.

OAuth 2.0 is a specification outlined in RFC 6749 that allows third-party services to make requests on behalf of a user without accessing passwords and other sensitive information. If you are unfamiliar with OAuth 2.0, check out Aaron Parecki’s “OAuth 2 Simplified” guide.

Simplifying OAuth 2.0 Integration with SDKs

To streamline the process of integrating the OAuth 2.0 flow into your app, we highly recommend leveraging available Software Development Kits (SDKs):

• Android
• iOS
• JavaScript

These SDKs are designed to handle the majority of complexities and edge cases, ensuring a smooth integration experience.

Performing Authorization Requests in a System Browser Component

For a secure and standardized user experience, it is crucial to execute the authorization request within a system browser component. We recommend the following components based on the respective platforms:

• Android: Custom Tabs
• iOS 13+: ASWebAuthenticationSession
• iOS before 13: SFSafariViewController
• Others: the default browser

The Oauth2 protocol is used for enabling Epidemic Sound Connect. Epidemic Sound Connect implements the Authorization Code Flow with Proof Key for Code Exchange (PKCE) in order for your application to get authorized.

Step 1: Authorize

Parameter	Description
Authorization Endpoint	https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/auth
Token Exchange Endpoint	https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token

To start the flow you make a GET request to the Auth URL Authorization Endpoint with the following parameters:

Parameter	Description
response_type	OAuth 2.0 response type, code is the only acceptable input at this time.
client_id	The client ID of your application found in the developer portal.
redirect_uri	The URI we will redirect back to after an authorization by the user. You need to whitelist the URI of your application in the developer portal.
code_challenge	Base64 encoding of an SHA256 hashed code_verifier. You can find more information here.
code_challenge_method	Set to "S256".
state (optional)	Randomly generated string to prevent CSRF attacks.

Example request

curl -G https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/auth \
-d 'client_id=test-client' \
-d 'response_type=code' \
-d 'redirect_uri=https://example.com/callback&state=15...Fe&code_challenge=zQ...mo&code_challenge_method=S256'

A successful request will redirect the user to the Epidemic Sound login page. After the user signs in, they will see a consent page, asking them to authorize your application. You can add the logo for your app in the developer portal.

Step 2: Receive redirect URI

After the user has authenticated and authorized your application, the user will be redirected to the specified redirect URI in step 1. The redirect URI will contain a single-use authorization code which expires in 10 minutes. It can look something like this:

Redirect URI with authorization code

'https://example.com/callback?state=15...Fe&session_state=43...07&code=36...71'

Note the code query param above, this is the authorization code you need for the next step.

Step 3: Get an access token

To get tokens a POST request to the Token URL endpoint is needed. The content type header must be set to application/x-www-form-urlencoded and the body must contain the following parameters:

Parameter	Description
grant_type	Set to "authorization_code"
redirect_uri	The redirect URI of your application is specified in the developer portal.
code	The code from the query parameter received with the redirect URI (can only be used once).
code_verifier	The code_verifier generated in previous step.
client_id	The client ID of your application found in the developer portal.

Example request using curl:

curl -X 'POST' https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=authorization_code&redirect_uri=https%3A%2F%example.com%2Fcallback&
  code=23a1834a-197a-4ac1-a9da-1bb775101d22.43a20f66-5cfc-492d-8845-33247821e607.
  76f3978b-b9c5-433e-aa39-bea295b7d571&
  code_verifier=ImbASEAFhVK7LTjmD02dPysUYtG2ZlFdMbldWpqyPVW5nQ442cK5sFLqCuvMmNoV&
  client_id=test-client'
'

Example of a response body

{
  "access_token": "eyJhbG…jZXddMA",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbG…rGUbbU_c",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "5c8686d3-0190-4e97-99cd-18add5e1d43d",
  "scope": "email profile"
}

To authenticate a request to the API, use the Authorization header with the access token as the bearer token: Authorization: Bearer [ACCESS_TOKEN].

Refresh an access token

To refresh an access token you need to send a POST request to the Token URL. The content type header must be set to application/x-www-form-urlencoded and the body should contain the following values:

• grant_type - Set to "refresh_token"
• client_id - Your client id found in the developers portal
• refresh_token - The refresh token acquired in the previous ste

Example request using curl

curl -X 'POST' https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'refresh_token=eyJhbG...ssw5c&grant_type=refresh_token&client_id=test-client'
'

Example of a succesful refresh of the access token

{
  "access_token": "eyJhbG…O1sByYg",
  "expires_in": 300,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbG…JLQKvY",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "5c8686d3-0190-4e97-99cd-18add5e1d43d",
  "scope": "email profile"
}

The response contains a new access token and a new refresh token. Replace the old tokens with the newly created ones.

Log out Epidemic Sound Connect

To log out the account make a POST request to the Log out URL end_session_endpoint with the following data:

• client_id - Your client id found in the developers portal
• refresh_token - The refresh token acquired in previous step

Example log out request using curl

curl -X 'POST' https://login.epidemicsound.com/auth/realms/accounts/protocol/openid-connect/logout \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'client_id=test-client&refresh_token=eyJhbG...tGoA'
'

If successful the response body will be empty and a HTTP status code 204.