Ads API Quick Start
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:
-
Create an application at developer.spotify.com to get a client ID and secret.
-
Configure a redirect URI for the application (e.g.,
http://localhost:8888/callback
). -
Accept the API Terms with your generated client id in Ad Studio.
-
* 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.
-
* 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:
-
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
(afterredirect_uri=
) with your callback URL.
-
Log in your Spotify account and authorize your application. Clicking Login returns a 404 error, but that’s ok.
-
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. -
Open a terminal window and run the command shown below. In this command, replace
client_id
andclient_secret
with your real client ID and secret. Save the output for Step 5.echo -n [client_id]:[client_secret] | base64
-
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'