Authentication

The Epidemic Sound Partner API (PAPI) supports two authentication methods. Choose based on whether your users have Epidemic Sound accounts.

Quick Comparison

	Partner Token Authentication	Connect (OAuth) Authentication
Pattern	Backend-assisted user authorization	Federated OAuth 2.0
Your users need ES accounts?	No	Yes — users must log in with their Epidemic Sound credentials
Token management	Partner token (backend) + User token (client)	OAuth access/refresh tokens (client)
Best for	Server-side integrations where you control the user experience	Apps where users already have ES subscriptions

Which should I use?

• Use Partner Token Authentication if you're building a product where your users don't have (or don't need) Epidemic Sound accounts. You manage authentication on your backend.
• Use Connect Authentication if your users are existing Epidemic Sound subscribers who want to access their personal library and liked tracks.
• Use both together if you want to offer a baseline experience to all users via Partner Token Authentication, while allowing Epidemic Sound subscribers to connect their accounts for personalized features.

Combining Both Methods

The two authentication methods are not mutually exclusive. A common pattern is to:

1. Use Partner Token Authentication as your default — all users get access to browse and use music
2. Offer Connect Authentication as an optional upgrade — users with Epidemic Sound accounts can link them to access personalized features like liked tracks

This gives you flexibility to serve all users while providing enhanced features for ES subscribers.

---

Content Access

Your content access level applies to Partner Token Authentication and is negotiated as part of your partnership agreement (curated collections or full catalogue). With Connect Authentication, users get access to the full library plus their personalized content.

For detailed information on content access levels and managing collections, see the FAQ.

---

Partner Token Authentication

Partner Token Authentication is a backend-assisted authorization flow designed for server-side integrations. Your users don't need Epidemic Sound accounts.

How it works

This flow uses two tokens:

1. Partner Token — Identifies your application. Store this on your backend only (never expose to clients).
2. User Token — Identifies individual users of your app. Can be stored on the client and used for API requests.

Typical integration flow:

1. Your backend stores the Partner Token (never exposed to clients)
2. Your frontend/mobile app requests a user token from your backend
3. Your backend fetches a User Token from Epidemic Sound using the Partner Token
4. Your backend returns the User Token to the frontend
5. Your frontend calls Epidemic Sound APIs directly using the User Token (CORS is supported)

Token Lifecycle

Token	Where to store	TTL	How to obtain
Partner Token	Backend (server-side only)	1 day	POST to /partner-token with your accessKeyId and accessKeySecret
User Token	Client (frontend)	7 days	POST to /token with a userId (using Partner Token in Authorization header)

Security

Never expose your Partner Token or API credentials on the client side. The Partner Token should only be used in backend-to-backend requests.

Step 1: Get your API credentials

To use the API, you need access to the Epidemic Sound Developer Portal. If you don't have access yet, see the Getting Started Prerequisites section.

Once you have portal access, you can obtain your accessKeyId and accessKeySecret:

• Your accessKeyId can be found in the Developer Portal under Authentication settings → API credentials for anonymous usage
• Your accessKeySecret is only shown once when generated. If lost, you will need to generate a new one from the portal.

Store credentials securely

Never commit your API credentials to version control. Store them securely on your backend, for example in environment variables or a .env file.

Step 2: Get a Partner Token

With your credentials, request a Partner Token from the /partner-token endpoint. The Partner Token has a TTL (Time To Live) of 1 day, after which a new one needs to be requested.

Step 3: 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 has a TTL of 7 days. 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 (OAuth) Authentication

Connect Authentication uses OAuth 2.0 to let your users log in with their Epidemic Sound accounts. This enables access to personalized content such as liked tracks.

User Login Required

This flow requires your users to have Epidemic Sound accounts. When using Connect, users will be redirected to the Epidemic Sound login page to authenticate.

When to use Connect

• Your users are existing Epidemic Sound subscribers
• You want users to access personalized content (liked tracks, playlists)
• You're building a consumer app where users manage their own ES accounts

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.