The Spotify Ad Studio API uses oAuth for authentication and access. Your API client will need an access token and secret before you can make any Ad Studio API calls. Review this section for information and instructions about how to get started.

Prerequisites

Make sure you have the following before proceeding:

  • A valid Spotify account. Sign up at Spotify.com if you don’t have an account. This can be a personal account or a separate account you want to use for developer access and work.

  • A valid Ad Studio account. Set up an Ad Studio Account if you don’t have one.

Set up your Ad Studio API application

Setting up your Ads API app is a one-time process. Follow these steps to get started:

  1. Create an application at developer.spotify.com to get a client ID and secret.

  2. Configure a redirect URI for the application (e.g., http://localhost:8888/callback).

  3. Accept the API Terms with your generated client id in Ad Studio.

  4. * Conditional * If you require access to Campaign Management capabilities, please fill in the pre-integration questionnaire here and the Spotify Ads API team will review your request within 3-5 business days. Skip this step if you only need access to Reporting capabiltiies.

  5. * Conditional * If you intend to onboard more than 25 users onto your app, please submit a quota extension request via the Developer Dashboard. Once you have submitted the request, a dedicated team at Spotify will review all the provided information and get back to you within six weeks.

Authenticate your Ad Studio account

Account authentication is the next step after you set up your application. Follow these steps to get started:

  1. Copy the authentication URL shown below into the address field of your browser.

    https://accounts.spotify.com/authorize/?client_id=[client_id]&response_type=code&scope=streaming&redirect_uri=callback_placeholder

    In the URL, replace:

    • client_id with your real client ID.
    • callback_placeholder (after redirect_uri=) with your callback URL.

  2. Log in your Spotify account and authorize your application. Clicking Login returns a 404 error, but that’s ok.

  3. Check the browser address bar for the parameter code=XXXXXXXX. The Xs are placeholders for your access code. The access code is valid for 10 minutes. Save the code for Step 5.

  4. Open a terminal window and run the command shown below. In this command, replace client_id and client_secret with your real client ID and secret. Save the output for Step 5.

    echo -n [client_id]:[client_secret] | base64

  5. Run the command shown below to generate an access token. A valid token is required to make API requests.

    curl -H "Authorization: Basic [BASE64_OUTPUT_FROM_STEP_4]" -d grant_type=authorization_code -d code=[CODE_FROM_STEP_3] -d redirect_uri=http://localhost:8888/callback https://accounts.spotify.com/api/token

    In this command, replace:

    • BASE64_OUTPUT_FROM_STEP_4 with the code from Step 4.
    • CODE_FROM_STEP_3 with the code from Step 3.

Authentication results

If you complete the previous steps successfully, you should see a response that looks similar to this:

{ "access_token": "XXXXXXXXXXXXX", "token_type": "Bearer", "expires_in": 3600, "refresh_token": "XXXXXXXXXXXX", "scope": "" }

The access token and bearer token give you access to the API endpoints for 1-hour. Save the refresh token in a safe place.

Using the refresh token

Your refresh token contains the information you need to request a new token. Run the following command in a terminal window when you need to renew API access with your refresh token:

curl -H "Authorization: Basic [BASE64_OUTPUT_FROM_STEP_4]" -d grant_type=refresh_token -d refresh_token=[REFRESH_TOKEN_FROM_RESULTS] https://accounts.spotify.com/api/token

In this command, replace:

  • BASE64_OUTPUT_FROM_STEP_4 with the output from Step 4 above.
  • REFRESH_TOKEN_FROM_RESULTS with the value of the refresh token returned by the response shown in the Authentication Results section above.

After refreshing the token, you can make an API request using the access token with the command shown below. In this command, replace ACCESS_TOKEN with the value of the access token returned by the response shown in the Authentication Results section above.

curl --request GET --url https://api-partner.spotify.com/ads-sandbox/v1/currentUser/adAccounts --header 'authorization: Bearer ACCESS_TOKEN'

Note:The refresh token does not expire but you can revoke access by updating your app’s users under ‘Users and Access’ section in the Developer Dashboard.