Authorization

Recommended method: access tokens

Use your client ID and client secret to request a short-lived access token, then send that token in the Authorization header on API requests.

The flow is:

1. Create API credentials in your Soundcharts dashboard.
2. Request an access token from the token endpoint.
3. Extract the access_token from the response.
4. Use the token as a bearer token when calling the API.
5. Request a new token when the current one expires.

Create credentials

Open your Soundcharts dashboard and create an API client in the Credentials section. The client provides the two values required to request an access token:

• client_id: identifies the API client.
• client_secret: authenticates the API client. Store it securely; it is only displayed once.

You can create up to 5 API clients for now. Use separate clients for production, staging, and local development when possible.

Request an access token

Make a POST request to the authorization service token endpoint. The request is authenticated with HTTP Basic authentication, using your client ID as the username and your client secret as the password.

curl -X POST https://account.soundcharts.com/oauth/token \
  -u "CLIENT_ID:CLIENT_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "team_id=YOUR_TEAM_NAME_OR_ID"

Extract the access token

A successful response is a JSON object containing the access token and metadata about how to use it.

{
  "access_token": "ACCESS_TOKEN",
  "token_type": "bearer",
  "expires_in": 3600,
  "refresh_token": null
}

Call the API

Pass the value returned in access_token as a bearer token in the Authorization header. The API call does not need x-app-id or x-api-key when you use this method.

curl https://customer.api.soundcharts.com/api/v2/artist/{uuid} \
  -H "Authorization: Bearer ACCESS_TOKEN"

Refresh an access token

There is no separate refresh request for this flow. When an access token expires, request a new one with the same client credentials.

Error handling

• 401 Unauthorized: the client ID or client secret is missing or invalid.
• 400 Bad Request: the request body is missing a required parameter or uses an unsupported grant_type.
• 403 Forbidden: the client is authenticated but cannot access the selected team or resource.
• 405 Method Not Allowed: the token endpoint was called with an unsupported HTTP method.
• 429 Too Many Requests: too many token requests were sent in a short period.

Legacy method: API keys

Existing integrations may continue to use the legacy headers:

• x-app-id: identifies your application and permissions.
• x-api-key: authenticates the request.

curl https://customer.api.soundcharts.com/api/v2/artist/{uuid} \
  -H "x-app-id: YOUR_APP_ID" \
  -H "x-api-key: YOUR_API_KEY"

Which method should I use?

Notes

• Always make requests over HTTPS.
• Generate separate credentials for production, staging, and experiments when possible.
• Rotate credentials if a secret is exposed or shared by mistake.