Okta Workflows Tutorial: Build a Connector for Spotify API (with OAuth 2.0)

This tutorial will teach you how to build a connector for Spotify API that uses OAuth for authentication using the Okta Workflows Connector Builder.

• Connector for Spotify API
• Build a connector for Spotify API
• Resources

Connector for Spotify API

You will build a connector for Spotify API because it uses OAuth for authentication. This tutorial will teach you how to create a connector in the Connector Builder that uses OAuth for authentication.

OAuth authentication is an advanced topic. If you are new to the Connector Builder, read and complete other articles and tutorials in this series: 

• Understanding Okta Workflows Connectors.
• Okta Workflows Tutorial: Build a Connector for OpenWeather API.

If you want to call Spotify API using the API Connector card, read this KB:

• How to Call Spotify API from Okta Workflows (OAuth Authentication Example).

This KB will teach you how to set up OAuth connection and call the Spotify API using the API Connector card.

Build a connector for Spotify API

In this section, you will build a connector to Spotify in the Connector Builder.

The Connector Builder uses Workflows flows and cards (action, function) to build a connector.

A connector consists of several flows:

• A flow to make HTTP requests.
• A flow to check authentication to the service is working.
• One or more action flows. Each action flow calls a service’s API endpoint.
• Custom action flow to allow calling any API endpoint on the service (see the Build a Connector for OpenWeather API tutorial).

First, you need a Spotify account before you start building the connector.

Set up a Spotify account and app

Create a Spotify account

1. Create a Spotify account, if you don’t have one.

Create an app

After implementing an authorization flow, the app will provide an access token to make calls to Spotify API.

1. To create an app, go to your Dashboard, click on the Create an app.
2. Enter Workflows Connector Builder for App name.
3. Enter Workflows Connector Builder app for App description.
4. Enter http://localhost:8080 for the Redirect URIs. You will change this value later.
5. Check Web API for Which API/SDKs are you planning to use?
6. Check the Developer Terms of Service checkbox.
7. Click Save to create the app.

Spotify app.

Create a connector project

Launch the Connector Builder

1. Click the menu next to your name to launch the Connector Builder.

Launch the Connector Builder.

Create a connector project

1. Click the ➕ in the left panel to create a connector project.
2. Enter Spotify for the Connector name.
3. Enter Spotify connector for the Connector description.
4. Click Save to create the project.

Spotify connector project.

Connector flows and authentication

Connector flows

The connector you will build has three flows:

• httpHelper: manages all authentication and HTTP requests for the connector.
• authPing: checks connection health.
• List User Albums: lists the current Spotify albums of users (API docs).

Authentication

Authentication is where you define the parameters required to create a secure connection to the API service.

When an end user creates a connection to your service, the New Connection dialog collects the specific authentication details.

There are three authentication types:

• Basic: uses username and password.
• OAuth 2.0: grants limited access to resources to a third party. You can use Authorization Code or Client Credential grant types in a connector.
• Custom: uses API key or other authentication process.

You will set up an OAuth connection for Spotify.

Create authentication for Spotify API

Create an OAuth connection

1. Scroll down and click on Set up authentication on the Overview page to create a connection.
2. Select Oauth 2.0 from the Auth Type list.
3. Select Authorization Code from the Grant Type.
4. Enter https://accounts.spotify.com for the Base URL.
5. Enter /authorize for the Authorize Path.
6. Enter /api/token for the Token Path.
7. Leave the Refresh Token Path field blank.

Creating a connection.

Update the Redirect URI in the Spotify app

1. Copy the link under Redirect URI. This is the callback URL.
2. Return to the Spotify app you created earlier. Click Settings.
3. At the bottom of the page, click Edit.
4. In the Redirect URIs section, click Remove to delete the current URI.
5. Paste the URI from the Connector Builder and click Add.
6. Click Save to save the changes.

Set up the Client ID and Client Secret

1. Return to the Connector Builder.
2. Keep Developer for the Client Ownership.
3. Copy the Client ID from the Spotify app and paste it into the Client ID field in the connection.
4. Copy the Client Secret from the Spotify app (click View client secret) and paste it into the Client Secret field in the connection.

Set up scope

The Get Current User’s Playlists API requires the playlist-read-private scope. Scopes define the resources to which the app has access. 

Creating new connection (continued).

1. In the Scopes section, click Add Scope.
2. Enter playlist-read-private for the Name.
3. The right side shows the connection preview. Click Save to create the connection.

Spotify connection information.

Create a flow to make HTTP requests

You will create a flow named httpHelper.

The httpHelper is a system flow that manages authentication and HTTP requests for the connector. The httpHelper flow is a helper flow; other flows can call it. The flow has:

• Several inputs.
• Function cards to build request query, header, and body information.
• The HTTP – Raw Request card to make a call to an API.
• Several outputs.

Create a flow

1. Open the Flows page.
2. To create a flow click + New Flow.
3. Click Unnamed in the upper left corner to name the flow.
4. Enter httpHelper for the Flow name.
5. Enter This flow manages all authentication and HTTP requests for the connector for the Description.
6. Check the Save all data that passes through the Flow? option.
7. To save the flow, click Save.

Set up flow inputs

1. Click Add event and choose Helper Flow.
2. Add the following fields on the Helper Flow card:
   • relative_url (type: Text).
   • request_method (Text).
   • query (Object).
   • headers (Object).
   • body (Object).

The httpHelper flow with inputs

httpHelper flow.

Set up the API URL

The connector can support multiple Spotify endpoints. The base URL stays the same, and the relative URL will change. You need to combine the two values into a full URL.

1. Add the Text – Concatenate card after the Helper Flow card.
2. Enter https://api.spotify.com the text 1 field.
3. Connect relative_url to the text 2 field.
4. Rename the card’s output field.
   • To edit the card, click ⚙️ > Edit card.
   • To rename the output field, click on its ✏️ icon and set the name to full_url.

Setting up the URL.

Set up the headers

You need to set up two header parameters:

• Content-Type: application/json.
• Authorization: Bearer access_token.

The connection you set up will acquire the access token. The Connection field lists the Access Token value in the first card.

To set up the Authorization header:

1. Add the Text – Compose card.
2. Type Bearer inside the card.
3. Connect Access Token after the string Bearer (add a space between the strings).
4. Rename the Compose card output field to bearer.

To set up the Content-Type header:

1. Add the Object – Construct card.
2. Create a Content-Type field and for the value enter application/json.
3. Create an Authorization field, and for the value connect the bearer field from the Compose card.
4. Rename the output field to headers_auth.

You need to merge the Content-Type and Authorization headers with any headers a Workflows user might provide.

1. Add the Object – Merge card.
2. Connect the headers field from the first card to the object 1 field.
3. Connect headers_auth from the Construct card to the object 2 field.
4. Rename the output field to merged_headers.

httpHelper flow with headers cards.

Make the API call

1. Add the HTTP – Raw Request card.
2. Create the following connections:
   • full_url to the url field on the Raw Request card.
   • request_method to the method on the Raw Request card.
   • merged_headers to the headers field on the Raw Request card.
   • query from the first card to the query field.
   • body to the body field.

Set up flow outputs

1. Connect statusCode, headers, and body fields from the HTTP – Raw Request card to the Flow Control – Return card.
2. Change the body field type to Object.

Final httpHelper flow:

httpHelper flow.

Test the flow

1. Click Run to test the flow.
2. Select New connection from the Test Connection list.
3. Enter Spotify for the Name field.
4. Enter Spotify connection for the Description field.
5. Click Create. You will see a popup asking you to sign into Spotify and allow the app you created (Workflows Connector Builder) to access your playlist information.
6. Enter /v1/me/playlists for the relative_url field.
7. Enter GET for the request_method field.
8. Click Run to test the flow.

Create a flow to check for a valid connection

You will create a flow named _authPing. An _authPing flow is a system flow used by the platform to call an API and check for valid authorization.

This action acts as a validation check and runs when you first authenticate the connector, add new connectors, or open flows.

Create a flow

1. Return to the connector project view.
2. Click + New Flow from the Flows page.
3. Click Add event, and select the Authping event.
4. To save the flow, click Unnamed in the upper left corner.
5. Enter _authping for the the Name.
6. Enter Connection health check for the description.
7. Check the Save all data that passes through the Flow? option.
8. Click Save.

_authping flow.

Add connection health check cards

1. Click Add function, and select Error Handling – If Error card.
2. In the Try block (automatically selected), click ➕, then function (calculator icon), and select the Flow Control – Call Flow card.
3. On the Call Flow card, click Choose Flow.
4. Select the httpHelper flow, and click Choose.

The flow looks like this:

_authping flow with the Call Flow card.

This flow calls the httpHelper flow to check the connection to the service is working. You must use an API endpoint that requires authentication.

Note: The Okta Workflows team recommends a request with the smallest response size. For example, some APIs have a /me endpoint to get information about the logged-in user.

The Spotify API has a /me endpoint you can use in this flow.

Finish configuring the Call Flow card:

1. Enter /v1/me for the relative_url.
2. Enter GET for the request_method.
3. Leave the query, headers, and body fields blank.
4. Connect the Connection field from the first card to the Connection field on the Call Flow card.

Calling the /me endpoint.

To create outputs on the Call Flow card:

1. Click inside the Click or drag to create area and create the following output fields:
   • statusCode (type Number).
   • headers (Object).
   • body (Object).

Call Flow card with outputs.

Next, you will set up a message when the connection is working and a message when the connection is not working.

To set up a message when for working connection:

1. Click the ➕ after the Call Flow card inside the If Error card and select the Flow Control – Assign card.
2. Add a message field and set it to The connection is successful value in the Control – Assign card.

Create outputs for the If Error card:

1. Click View Outputs in the If Error card (upper right corner). The card opens a section where you define the card’s outputs.
2. Click inside the field box and create two outputs:
   • statusCode.
   • message.
3. Create the following connections:
   • statusCode from the Call Flow card to the statusCode‘s first sub-field.
   • message from the Assign card to the message‘s first sub-field.

The cards look like this:

Set up a message when the connection is working.

To set up a message when the connection is not working:

1. Using the list where it says Try, switch to the If Error block on the If Error card.
2. Add two fields to the Error object:
   • statusCode (type Text).
   • description (Text).
3. Click ➕ to the right of the Error object inside the If Error block and add the Text – Concatenate card.
4. Create the following connections:
   • description from the Error object to the text 1 field.
   • Enter : (colon) in the text 2 field.
   • Click to create a third field and connect message from Error to it.

Next, you will connect the message to the If Error card output.

1. Click View Outputs on the If Error card.
2. Create the following connections:
   • statusCode from Error to the statusCode‘s second sub-field.
   • output from Concatenate to the message‘s second sub-field.

The cards look like this:

Set up a message when the connection is not working.

Set up flow output

The Flow Control – Return Status card has two fields: working and serviceResponse. You will use the information available in this flow to set these fields.

1. Click ➕ after the If Error card and add the True/False – Compare card.
2. Connect statusCode from If Error card output to value a field.
3. Enter 200 for the value b field.
4. Rename the result output field to working.

Setting up connection status code.

If the call to the API is successful (200), the connection is working.

1. Click ➕ after the True/False – Compare card and add the Object – Construct card.
2. Create two fields on the Construct card:
   • statusCode (type Text).
   • body (Text).
3. Create the following connections:
   • statusCode from If Error card output to the statusCode field on the Construct card.
   • message from If Error card output to to body field on the Construct card.
4. Rename the output field on the Construct card to serviceResponse.

Setting up connection status response.

To set up flow outputs:

1. Connect the working from the Compare card to the working field on the Return Status card.
2. Connect serviceResponse from the Construct card to the serviceResponse field on the Return Status card.

The complete flow:

The complete _auththing flow.

Test the flow

1. Save the flow.
2. Click Run.
3. Select the Spotify connection and click Run.

Create an action to list user’s albums

In this section, you will create a connector action for the Get Current User’s Playlists endpoint.

Create a flow

1. Go back to the connector’s project view.
2. Click + New Flow to create a new flow.
3. Click Unnamed in the upper left corner to name the flow.
4. Enter List Current User Albums for the Flow name.
5. Enter List current user Spotify albums for the Description.
6. Check the Save all data that passes through the Flow? option
7. Click Save to save the flow.

Configure the flow as an action

An action flow makes a service API call.

To set up this flow as an action flow:

1. Click Add event and then Action event type.

The action flow doesn’t need inputs since the Get Current User’s Playlists endpoint doesn’t have inputs.

The flow looks like this:

List Current User Albums action.

Call the Spotify API

In this step, you will make a call to Spotify API.

1. Add the Flow Control – Call Flow card.
2. Click Choose Flow, select the httpHelper flow and click Choose.
3. Enter /v1/me/playlists for the relative_url field.
4. Enter GET for the request_method.
5. Connect the Connection field from the first card to the Connection field on the Call Flow card.
6. Create three outputs for the Call Flow card:
   • statusCode (type Number).
   • headers (Object).
   • body (Object).

Call Flow card.

Create flow outputs

Create the following outputs on the Flow Control – Return Outputs card:

1. Click Add Outputs.
2. Open Add group and select Add Static Group.
3. Create three outputs:
   • Status Code (type Number).
   • Headers (Object).
     • Delete the empty key entry.
   • Body (Object).
     • Delete the empty key entry.
4. Click Apply to save the outputs.
5. Connect data from the Call Flow card to the Return Outputs card:
   • statusCode to the Status Code field.
   • headers to the Headers field.
   • body to the Body field.

The end of the flow looks like this:

The complete List Current User Albums action flow.

Test the flow

1. Click Run to test the flow.
2. Select the Spotify connection from the Test Connection list and click Run.

Deploy the connector`

Turn flows on

Flows need to be on before deploying.

1. Return to the Flows page.
2. Turn the three flows on.

Update connector settings

In this section you will enter additional information in settings.

1. Return to the main project view.
2. Open to the Overview page.
3. Click Edit in the Settings section.
4. Download and set the Spotify icon for the connector.
5. Change the Accent Color if you want.
6. Enter User Documentation URL and Support Contact Email information.
7. Click Save to save all changes.

Connector settings.

Deploy the connector

To deploy the connector:

1. Switch to the Deployment tab.
2. Click Create test version.
3. Select the three vertical dots under Actions for a test version you created and select Deploy Version.

You will see the connector deployed in the Private deployment section.

Connector deployment.

You are ready to use the connector in a flow.

Using the connector in a flow

In this step, you will use the connector action in a flow.

Spotify connector.

Add the card

Spotify connector action.

1. Create a new flow in Workflows.
2. Click Add app action and select the Spotify connector. You can also search for it.
3. Select the Spotify – List Current User Albums action.

Create a connection

1. Click on + New Connection and follow the steps to create a connection for Spotify.

Spotify – List Current User Albums action.

Test

1. Test the card or the flow.

Testing the flow.

Congratulations

Nice work!

You built a connector for Spotify that leverages OAuth for authentication. 

Resources

📚 Building a Custom Connector in Okta Workflows, a Video Series.

📖 Okta Workflows Connector Builder documentation.

🍫 Get help from Workflows specialists during weekly community office hours.

📺 Learn from Workflows videos.

🛟 Get help from support: discuss a Workflows topic or ask a question.

🙋🏻‍♀️ Get help from the community: join the #okta-workflows channel on MacAdmins Slack.