The authorization code flow is suitable for long-running applications (e.g. web and mobile apps) where the user grants permission only once.

If you’re using the authorization code flow in a mobile app, or any other type of application where the client secret can’t be safely stored, then you should use the PKCE extension. Keep reading to learn how to correctly implement it.

The following diagram shows how the authorization code flow works:

Authorization Code Flow authorization code flow

Prerequisites

This guide assumes that you have created an app following the app settings guide.

Source Code

You can find an example app implementing authorization code flow on GitHub in the web-api-auth-examples repository.

Request User Authorization

The first step is to request authorization from the user, so our app can access to the Spotify resources in behalf that user. To do so, our application must build and send a GET request to the /authorize endpoint with the following parameters:

Query Parameter Value
client_id Required
The Client ID generated after registering your application.
response_type Required
Set to code.
redirect_uri Required
The URI to redirect to after the user grants or denies permission. This URI needs to have been entered in the Redirect URI allowlist that you specified when you registered your application (See the app settings guide). The value of redirect_uri here must exactly match one of the values you entered when you registered your application, including upper or lowercase, terminating slashes, and such.
state Optional, but strongly recommended
This provides protection against attacks such as cross-site request forgery. See RFC-6749.
scope Optional
A space-separated list of scopes.If no scopes are specified, authorization will be granted only to access publicly available information: that is, only information normally visible in the Spotify desktop, web, and mobile players.
show_dialog Optional
Whether or not to force the user to approve the app again if they’ve already done so. If false (default), a user who has already approved the application may be automatically redirected to the URI specified by redirect_uri. If true, the user will not be automatically redirected and will have to approve the app again.

If you are implementing the PKCE extension, you must include these additional parameters:

Query Parameter Value
code_challenge_method Required.
Set to S256.
code_challenge Required.
Set to the code challenge that your app calculated in step 1.

In order to generate the code_challenge, your app should hash the code verifier using the SHA256 algorithm. The code verifier is a random string between 43 and 128 characters in length. It can contain letters, digits, underscores, periods, hyphens, or tildes.

Example

The following JavaScript code example implements the /login method using Express framework to initiates the authorization request:

var client_id = 'CLIENT_ID';
var redirect_uri = 'http://localhost:8888/callback';

var app = express();

app.get('/login', function(req, res) {

  var state = generateRandomString(16);
  var scope = 'user-read-private user-read-email';

  res.redirect('https://accounts.spotify.com/authorize?' +
    querystring.stringify({
      response_type: 'code',
      client_id: client_id,
      scope: scope,
      redirect_uri: redirect_uri,
      state: state
    }));
});

Once the request is processed, the user will see the authorization dialog asking to authorize access within the user-read-private and user-read-email scopes.

The Spotify OAuth 2.0 service presents details of the scopes for which access is being sought. If the user is not logged in, they are prompted to do so using their Spotify credentials. When the user is logged in, they are asked to authorize access to the data sets or features defined in the scopes.

Finally, the user is redirected back to your specified redirect_uri. After the user accepts, or denies your request, the Spotify OAuth 2.0 service redirects the user back to your redirect_uri. In this example, the redirect address is https://localhost:8888/callback

Response

If the user accepts your request, then the user is redirected back to the application using the redirect_uri passed on the authorized request described above.

The callback contains two query parameters:

Query Parameter Value
code An authorization code that can be exchanged for an Access Token.
state The value of the state parameter supplied in the request.

For example:

https://my-domain.com/callback?code=NApCCg..BkWtQ&state=34fFs29kd09

If the user does not accept your request or if an error has occurred, the response query string contains the following parameters:

Query Parameter Value
error The reason authorization failed, for example: “access_denied”
state The value of the state parameter supplied in the request.

For example:

https://my-domain.com/callback?error=access_denied&state=34fFs29kd09

In both cases, your app should compare the state parameter that it received in the redirection URI with the state parameter it originally provided to Spotify in the authorization URI. If there is a mismatch then your app should reject the request and stop the authentication flow.

Request Access Token

If the user accepted your request, then your app is ready to exchange the authorization code for an Access Token. It can do this by making a POST request to the /api/token endpoint.

The body of this POST request must contain the following parameters encoded in application/x-www-form-urlencoded:

REQUEST BODY PARAMETER VALUE
grant_type Required
This field must contain the value "authorization_code".
code Required
The authorization code returned from the previous request.
redirect_uri Required
This parameter is used for validation only (there is no actual redirection). The value of this parameter must exactly match the value of redirect_uri supplied when requesting the authorization code.

If you are implementing the PKCE extension, these additional parameters must be included as well:

REQUEST BODY PARAMETER VALUE
client_id Required.
The client ID for your app, available from the developer dashboard.
code_verifier Required.
The value of this parameter must match the value of the code_verifier that your app generated in the previous step.

The request must include the following HTTP headers:

HEADER PARAMETER VALUE
Authorization Required
Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>
Content-Type Required
Set to application/x-www-form-urlencoded.

Example

This step is usually implemented within the callback described on the request of the previous steps. The following example implements the Access Token request inside the callback method:

app.get('/callback', function(req, res) {

  var code = req.query.code || null;
  var state = req.query.state || null;

  if (state === null) {
    res.redirect('/#' +
      querystring.stringify({
        error: 'state_mismatch'
      }));
  } else {
    var authOptions = {
      url: 'https://accounts.spotify.com/api/token',
      form: {
        code: code,
        redirect_uri: redirect_uri,
        grant_type: 'authorization_code'
      },
      headers: {
        'Authorization': 'Basic ' + (new Buffer(client_id + ':' + client_secret).toString('base64'))
      },
      json: true
    };
  }
});

Response

On success, the response will have a 200 OK status and the following JSON data in the response body:

KEY VALUE TYPE VALUE DESCRIPTION
access_token string An Access Token that can be provided in subsequent calls, for example to Spotify Web API services.
token_type string How the Access Token may be used: always “Bearer”.
scope string A space-separated list of scopes which have been granted for this access_token
expires_in int The time period (in seconds) for which the Access Token is valid.
refresh_token string A token that can be sent to the Spotify Accounts service in place of an authorization code. (When the access code expires, send a POST request to the Accounts service /api/token endpoint, but use this code in place of an authorization code. A new Access Token will be returned. A new refresh token might be returned too.)

The following example, shows how the successful response looks like:

{
   "access_token": "NgCXRK...MzYjw",
   "token_type": "Bearer",
   "scope": "user-read-private user-read-email",
   "expires_in": 3600,
   "refresh_token": "NgAagA...Um_SHo"
}

Request a refreshed Access Token

Access tokens are deliberately set to expire after a short time, after which new tokens may be granted by supplying the refresh token originally obtained during the authorization code exchange.

In order to refresh the token, a POST request must be sent with the following body parameters encoded in application/x-www-form-urlencoded:

REQUEST BODY PARAMETER VALUE
grant_type Required Set it to refresh_token.
refresh_token Required The refresh token returned from the authorization code exchange.

If you are implementing the PKCE extension, this additional parameter must be also included:

REQUEST BODY PARAMETER VALUE
client_id Required.
The client ID for your app, available from the developer dashboard.

The headers of this POST request must contain the following parameters, except if you are implementing PKCE where only Content-Type is required:

HEADER PARAMETER VALUE
Authorization Required
Base 64 encoded string that contains the client ID and client secret key. The field must have the format: Authorization: Basic <base64 encoded client_id:client_secret>
Content-Type Required
Always set to application/x-www-form-urlencoded.

Example

The following example retrieves a refreshed Access Token once the current one has expired:

app.get('/refresh_token', function(req, res) {

  var refresh_token = req.query.refresh_token;
  var authOptions = {
    url: 'https://accounts.spotify.com/api/token',
    headers: { 'Authorization': 'Basic ' + (new Buffer(client_id + ':' + client_secret).toString('base64')) },
    form: {
      grant_type: 'refresh_token',
      refresh_token: refresh_token
    },
    json: true
  };

  request.post(authOptions, function(error, response, body) {
    if (!error && response.statusCode === 200) {
      var access_token = body.access_token;
      res.send({
        'access_token': access_token
      });
    }
  });
});

The response will be similar to this:

{
   "access_token": "NgA6ZcYI...ixn8bUQ",
   "token_type": "Bearer",
   "scope": "user-read-private user-read-email",
   "expires_in": 3600
}

What’s next?

Learn how to use an access token to fetch track information from the Spotify Web API in the How to use the Access Token guide.