This guide covers four ways to call an API in Workflows.

• Okta Workflows

There are four ways to call an API in Workflows:

1. Using the built-in connector
2. Using the built-in connector custom API
3. Using a raw HTTP request
4. Using a connector built with the Connector Builder

Using the built-in connector

Workflows provides over 50 pre-built connectors to various services.
 
 

Every connector has actions (API endpoint) that can be called.

The following are actions (API endpoints) available in the Okta connector:

To call the Activate User action, add the action’s card:
   

Behind the scenes, the card calls the Okta API to activate a user.

Every card action has fields (parameters) defined that correspond to the behind-the-scenes API. In the example above, it is a single parameter ID or Login.

Before an action can be called, the service connection needs to be set up.

Every pre-built connector will have a different connection setup. Multiple connections for the same service are also possible. For example, one connection for testing and another for production.

When using a connector for the first time, there will be a prompt to create a connection to the service. For instance, this is the screen to set the Okta connection (docs):

Here is another example using Gmail.

The following are actions from the Gmail connector:

Before a Gmail action can be used, a connection must be created, where the authorization process appears as follows:

To send an email, add the Send Email card:

Behind the scenes, the card calls the Gmail API to send an email.

This card defines multiple fields (parameters) based on the Gmail API.

When to use the built-in connector?

The built-in connector is usually the most straightforward way to call an API service from Workflows. If a built-in connector is available and possesses the required actions, it should be utilized.

But sometimes, a service connection will not have all the actions pre-built or all the parameters available. In this case, the custom API action from the next section must be used.

Using the built-in connector custom API

Use the Custom API Action card if the built-in connection does not have the action (API) needed.

Every connector in Workflows has an action called Custom API Action.

This action allows calling any API endpoint available on the connector. Re-use the service connection but specify the API endpoint and parameters.

The Shopify connector has a built-in action to create a new customer.

But there is an action to list customers on the connector. To list customers, use the Shopify – Custom API Action card. Re-use the connection and specify the API endpoint to list customers:

Enter the Relative URL and, optionally, the Query and Header fields.

Go to the service API documentation to learn about the service URL, query, and header fields.

When to use the built-in connector custom API?

1. If the built-in connector does not have the action (API) needed.
2. If the connector in use has a built-in action but does not expose a specific parameter, the Custom API Action card should be used to make a request specifying the required parameter.

Using a raw HTTP request

If needed to call a service without a built-in connector, use the raw HTTP request.

Workflows has the API Connection card, which allows making HTTP requests to any API endpoint.
    

When using the API Connection card, specify the full API endpoint URL, authentication, and any query and body parameters.

ShipEngine has API to help with shipping and logistics. Workflows does not have a pre-built connection for ShipEngine. To call ShipEngine API, use the API Connector card.

ShipEngine has an API to validate an address. Call this API in Workflows using the API Connector – Post card.

Configure the URL, Query, Headers, and the request Body using the service docs.

If an API is used frequently, the authentication can be moved into a connection, allowing for the re-use of the connection in other flows.

Creating a connection for the ShipEngine API looks like this:

The API Connector card can use this connection, and no longer needs to set the Headers field:

If the absolute closest approximation to a raw API request in Workflows is needed, use the API Connector – Raw Request action.

When to use a raw HTTP request?

1. The required API is not on the list of pre-built connectors.
2. Control over the request is needed.

Using a connector built with the Connector Builder

To have an API available in the app action list, a custom connector for the API can be created using the Connector Builder. The connection will be listed here:

There are two online meetups about the Connector Builder:

• Getting Started with Okta Workflows Connector Builder
• Building with Okta Workflows Connector Builder - Advanced Topics

When to use the Connector Builder to create a connector?

• Simplify API usage within the organization.
• People within the organization can use the API via a custom-built-in connector instead of setting up API requests manually.

Related References

• Making API Requests in Okta Workflows | Workflows Online Meetup
• How to Call an API When It is Not Available From an Existing Card (Connection)
• Getting Started with Okta Workflows Connector Builder | Workflows Online Meetup
• Building with Okta Workflows Connector Builder – Advanced Topics | Workflows Online Meetup