API Key Authentication

API Key Authentication is the recommended authentication method for server-side integrations. It is a full replacement for both Partner Token and User Token authentication — everything those methods could do, an API key can do too, with a simpler setup.

Instead of exchanging credentials for short-lived tokens, you use a single long-lived API key directly in every request.

When to use this

API Key Authentication is intended for backend-only integrations. The API key must never be exposed to client-side code. All calls to the Epidemic Sound API should be made from your server.

---

How it works

Your API key is placed directly in the Authorization header of every request — the same header position used by JWT bearer tokens:

Authorization: Bearer your-api-key

There are no intermediate steps. No token exchange, no separate credential handshake — just your API key and the request.

Typical integration flow

1. Your API key is stored securely in your backend environment (e.g. an environment variable or secrets manager)
2. Your backend attaches the API key as a bearer token to every outgoing request to the Epidemic Sound API
3. Your frontend calls your own backend — it never communicates with the Epidemic Sound API directly

---

Step 1: Get your API key

API keys are provisioned through the Epidemic Sound Developer Portal. If you don't have access yet, see the Getting Started Prerequisites section.

Once you have portal access, your API key can be found under Authentication settings → API keys.

Store your API key securely

Never commit your API key to version control. Store it in an environment variable or a secrets manager on your backend — never in client-side code or API responses.

---

Step 2: Make authenticated requests

Add your API key as a bearer token in the Authorization header of every request:

Example request

curl -X 'GET' 'https://partner-content-api.epidemicsound.com/v0/tracks' \
  -H 'accept: application/json' \
  -H 'Authorization: Bearer your-api-key'

That's it. No prior token-fetch step required.

---

Step 3: Identify your users

All requests made with an API key share the same credential, so Epidemic Sound cannot attribute individual requests to your end users unless you tell it who is making each request.

Pass your end user's ID in the x-partner-user-id header on every request. This gives Epidemic Sound per-user visibility for logging, analytics — the same level of attribution as the old User Token approach.

Example request with per-user context

curl -X 'GET' 'https://partner-content-api.epidemicsound.com/v0/tracks/search?term=upbeat' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'x-partner-user-id: user-abc-123'

GDPR note

Use a stable, anonymised identifier for your end user — not their name or email address. The value must be safe to share with third parties.

---

Endpoint access

API Key Authentication has full endpoint parity with Partner Token and User Token authentication combined. Every endpoint previously accessible with either of those token types is accessible with an API key. Your content access level (curated collections or full catalogue) is still determined by your partnership agreement.

Endpoint Category	Partner Token	User Token	API Key
Browse & Search	✗	✓	✓
Streaming & Download	✗	✓	✓
Audio Upload	✓	✗	✓
Get Audio by Checksum	✓	✓	✓
Usage Reporting (/v0/usage)	✗	✓	✓
Bulk Reporting	✓	✗	✓

The one thing an API key cannot do is generate a User Token — but with API Key Authentication, there is no need for one.

---

Reporting usage

Use POST /v0/analytics/report to report when your users preview, download, or export tracks. Include an explicit userId in each event so activity is correctly attributed per user.

Example: report a preview and a download for two different users

curl -X 'POST' 'https://partner-content-api.epidemicsound.com/v0/analytics/report' \
  -H 'Authorization: Bearer your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [
      {
        "userId": "user-abc",
        "timestamp": "2026-03-30T10:00:00Z",
        "userConnected": false,
        "analyticsEvent": {
          "trackId": "some-track-id",
          "type": "trackPreviewed"
        }
      },
      {
        "userId": "user-xyz",
        "timestamp": "2026-03-30T10:01:00Z",
        "userConnected": false,
        "analyticsEvent": {
          "trackId": "some-track-id",
          "format": "mp3",
          "quality": "normal",
          "type": "trackDownloaded"
        }
      }
    ]
  }'

---

Migration Guide

This section is for integrations currently using Partner Token Authentication who are switching to API Key Authentication.

What changed

The old flow required two separate API calls before you could make any content request:

1. Exchange accessKeyId + accessKeySecret for a Partner Token (TTL: 1 day)
2. Exchange the Partner Token + a userId for a User Token (TTL: 7 days)
3. Use the User Token for content API calls

API Key Authentication replaces this entire flow with a single credential used directly. It has full parity with both token types — you do not lose access to any endpoint by switching.

Reporting usage

The old POST /v0/usage endpoint identified the user implicitly via the User Token. With API Key Authentication there is no per-user token, so POST /v0/analytics/report is the replacement — it works the same way but requires an explicit userId in each event. See Reporting usage above for an example.

Before and after

Before — three steps to make a single API call:

const axios = require('axios')

const API_URL = 'https://partner-content-api.epidemicsound.com'

// Step 1: exchange credentials for a Partner Token (TTL: 1 day)
async function getPartnerToken() {
  const res = await axios.post(`${API_URL}/v0/partner-token`, {
    accessKeyId: 'your-key-id',
    accessKeySecret: 'your-key-secret',
  })
  return res.data.accessToken
}

// Step 2: exchange Partner Token for a User Token (TTL: 7 days)
async function getUserToken(partnerToken, userId) {
  const res = await axios.post(
    `${API_URL}/v0/token`,
    { userId },
    { headers: { Authorization: `Bearer ${partnerToken}` } }
  )
  return res.data.accessToken
}

// Step 3: finally make the actual API call
async function getCollections() {
  const partnerToken = await getPartnerToken()
  const userToken = await getUserToken(partnerToken, 'user-123')

  const res = await axios.get(`${API_URL}/v0/collections`, {
    headers: { Authorization: `Bearer ${userToken}` },
  })
  return res.data
}

After — one step:

const axios = require('axios')

const API_URL = 'https://partner-content-api.epidemicsound.com'
const API_KEY = process.env.EPIDEMIC_SOUND_API_KEY

async function getCollections() {
  const res = await axios.get(`${API_URL}/v0/collections`, {
    headers: { Authorization: `Bearer ${API_KEY}` },
  })
  return res.data
}