SpotifyAPIServer

A server that handles the process of retrieving the authorization information and refreshing tokens for the Spotify web API on behalf of your frontend app. Supports the Client Credentials Flow, Authorization Code Flow, and Authorization Code Flow with Proof Key for Code Exchange.

Can be run as a local server directly from Xcode. It will run on http://127.0.0.1:7000.

This sever can be used with SpotifyAPI. See Using a Backend Server to Retrieve the Authorization Information for more information.

Can also be used with the Spotify iOS SDK. Assign /authorization-code-flow/retrieve-tokens to the "tokenSwapURL" and /authorization-code-flow/refresh-tokens to "tokenRefreshURL".

Table of Contents

• Environment
• Deploying to Heroku
• Deploying to AWS
• Endpoints
• Errors

Environment

Requires the following environment variables:

• CLIENT_ID: Your client id from Spotify.
• CLIENT_SECRET: Your client secret from Spotify.
• REDIRECT_URI: The redirect URI. Can be omitted if this value is sent in the body of requests to the /authorization-code-flow/retrieve-tokens or /authorization-code-flow-pkce/retrieve-tokens endpoints. If both are present, then the value sent in the body of the request takes precedence. If you are using this server with the Spotify iOS SDK, then you must set this value, as it will not be sent in the body of the request to the /authorization-code-flow/retrieve-tokens endpoint.
• SECRET_KEY: A randomly generated string that is used to generate a key for encryption. No specific length is required, but generally it should be at least 20 characters. This key is used to encrypt and decrypt the refresh token returned by Spotify. Warning: If you change this value, then any previously-retrieved authorization information will be invalidated.
• LOG_LEVEL: Not required, but can be used to change the log level of the loggers used by Vapor (but not the ones used by SpotifyAPI). See here for more information. See here for how to retrieve the logs from Heroku.

Deploying to Heroku

This server is pre-configured for deployment to Heroku (although any platform can be used).

One-Click Deployment

Manual Deployment

First, sign up for a Heroku account, install the command-line tool, login, and create a Heroku application, as described here. Clone this repository and set it as the working directory. Then, run the following command:

heroku git:remote -a [app name]

where app name is the name of the application that you just created on Heroku. This command adds a custom remote to your repository called heroku; pushing to it causes your app to be deployed.

Next, set the buildpack to teach heroku how to deal with vapor:

heroku buildpacks:set vapor/vapor

Finally, deploy to Heroku by running the following:

git push heroku main

See here for how to configure the above-mentioned environment variables on heroku.

Deploying to AWS

This server is also available as a docker image in the Amazon ECR Public Gallery. You can sign up for an AWS account here. Create an App Runner service here. Choose "Container registry" for "Repository type" and "Amazon ECR Public" for "Provider". For "Container image URI," use public.ecr.aws/h4z3r8p2/spotify-api-server:latest. Then, click next. Configure the environment variables as described above. For "Port," use 8080. Follow the prompts to create the service.

Read more about App Runner here.

Endpoints

GET /

Returns the text "success". Used to indicate that the server is online.

POST /client-credentials-flow/retrieve-tokens

Retrieves the authorization information for the Client Credentials Flow.

A request to this endpoint can be made by ClientCredentialsFlowProxyBackend.makeClientCredentialsTokensRequest(). Assign this endpoint to ClientCredentialsFlowProxyBackend.tokensURL.

Request

Header: Content-Type: application/x-www-form-urlencoded

The body must contain the following in x-www-form-urlencoded format:

<table> <thead> <tr> <th>Request Body Parameter</th> <th>Value</th> </tr> </thead> <tbody> <tr> <td>grant_type</td> <td><code>client_credentials</code></td> </tr> </tbody> </table>

See ClientCredentialsTokensRequest, which can be used to encode this data.

Response

Header: Content-Type: application/json

Returns the authorization information as JSON data that can be decoded into AuthInfo. The accessToken and expirationDate (which can be decoded from the "expires_in" JSON key) properties should be non-nil. For example:

{
    "access_token": "NgCXRKc...MzYjw",
    "token_type": "bearer",
    "expires_in": 3600,
}

Read more at the Spotify web API reference.

POST /authorization-code-flow/retrieve-tokens

Retrieves the authorization information for the Authorization Code Flow.

A request to this endpoint can be made by AuthorizationCodeFlowProxyBackend.requestAccessAndRefreshTokens(code:redirectURIWithQuery:). Assign this endpoint to AuthorizationCodeFlowProxyBackend.tokensURL.

Request

Header: Content-Type: application/x-www-form-urlencoded

The body must contain the following in x-www-form-urlencoded format:

<table> <thead> <tr> <th>Request Body Parameter</th> <th>Value</th> </tr> </thead> <tbody> <tr> <td>grant_type</td> <td><code>authorization_code</code></td> </tr> <tr> <td>code</td> <td>The authorization code returned from the initial request to the <code>/authorize</code> endpoint.</td> </tr> <tr> <td>redirect_uri</td> <td>The redirect URI, which must match the value your app supplied when requesting the authorization code. Can be omitted if this value is stored in the <code>REDIRECT_URI</code> environment variable.</td> </tr> </tbody> </table>

See ProxyTokensRequest, which can be used to encode this data.

Response

Header: Content-Type: application/json

Returns the authorization information as JSON data that can be decoded into AuthInfo. The accessToken,refreshToken, and expirationDate (which can be decoded from the "expires_in" JSON key) properties should be non-nil. For example:

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

Read more at the Spotify web API reference.

POST /authorization-code-flow/refresh-tokens

Refreshes the access token for the Authorization Code Flow.

A request to this endpoint can be made by AuthorizationCodeFlowProxyBackend.refreshTokens(refreshToken:). Assign this endpoint to AuthorizationCodeFlowProxyBackend.tokenRefreshURL.

**Requ