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.

Set up your Ad Studio API application

You only do this once. Follow these steps to get started:

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

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

  3. Contact Ad Studio API support to whitelist your client ID (if you haven’t done this already).

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. You a valid token 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=[ACCESS_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.
  • ACCESS_TOKEN_FROM_RESULTS with the value of the access 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 application access. you can revoke access for your application by managing your users in the developer dashboard.