Four Ways to Call an API in Okta Workflows
Last Updated:
Overview
Okta Workflows provides four distinct methods for calling an Application Programming Interface (API). Okta Workflows can call external service APIs through pre-built connectors, custom connector actions, raw HTTP requests, and custom connectors. This article outlines when each option fits best and how each option maps to connection setup, endpoint access, and request control.
Applies To
- Okta Identity Engine (OIE)
- Okta Classic Engine
- Okta Workflows
- Application Programming Interface (API) Integrations
- Custom API Requests
- Connector Builder Use Cases
Solution
What are the four ways to call an API in Okta Workflows?
Review the four ways to call an API in Okta Workflows in the following list:
- Using the built-in connector.
- Using the built-in connector custom API.
- Using a raw HTTP request.
- Using a connector built with the Connector Builder.
How is a built-in connector used?
Okta Workflows provides over 50 pre-built connectors to various services.
Each connector includes actions that correspond to API endpoints.
The following image shows actions available in the Okta connector.
Adding a card calls the mapped API action. For example, the Activate User card calls the Okta API operation to activate a user.
Each card defines fields that correspond to the underlying API parameters. In this example, the card uses the ID or Login field.
A service connection must exist before a card can call an action.
Each pre-built connector uses its own connection setup. Okta Workflows also supports multiple connections for the same service, such as one connection for testing and another for production.
When an administrator uses a connector for the first time, Okta Workflows prompts for connection creation. The following image shows Okta connector authorization details from the Okta connector authorization documentation.
The same pattern applies to other connectors such as Gmail.
The following image shows actions from the Gmail connector.
A Gmail connection must exist before the connector can run an action.
The Send Email card then uses that connection to call the Gmail API.
When does a built-in connector fit best?
A built-in connector usually provides the most direct way to call an API service from Okta Workflows.
Use a built-in connector when:
- A pre-built connector exists for the service.
- The connector includes the required action.
- The exposed card fields include the required parameters.
If the connector does not include the required action or parameter, the Custom API Action card provides the next option.
How is the pre-built connector Custom API used?
Use the Custom API Action card when the built-in connector does not include the required action.
Each connector in Okta Workflows includes a Custom API Action.
This action can call any API endpoint available for that connector while reusing the existing service connection. The card requires the endpoint details and any relevant parameters.
The Shopify connector includes a built-in action to create a customer.
To list customers instead, the Shopify – Custom API Action card can reuse the same connection and call the Shopify endpoint to list customers.
Enter the Relative URL field and, if needed, the Query and Header fields. Service API documentation defines the correct URL, query, and header values.
When should the Custom API Action card be used?
Use the Custom API Action card when:
- The built-in connector does not include the required action.
- The built-in connector includes the action, but does not expose a required parameter.
How is a Raw HTTP request used?
Use a raw HTTP request when no pre-built connector exists or when the request needs more control.
Okta Workflows includes the API Connection card, which can send HTTP requests to any API endpoint.
The API Connection card requires the full endpoint URL, authentication details, and any query or body parameters.
ShipEngine provides APIs for shipping and logistics. Okta Workflows does not include a pre-built ShipEngine connector, so the API Connector card can call the ShipEngine API directly.
ShipEngine provides an API to validate an address. The API Connector – Post card can call that endpoint by using the service documentation to configure the URL, query, headers, and request body.
If the same API is used frequently, a reusable connection can hold the authentication details.
The API Connector card can then use that connection and omit the Headers field.
If the closest option to a raw API request is required in Okta Workflows, use the API Connector – Raw Request action.
When should a raw HTTP request be used?
Use a raw HTTP request when:
- The required API does not appear in the list of pre-built connectors.
- The request needs direct control over endpoint details, authentication, headers, query values, or body values.
How is a connector built with the Connector Builder used?
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 should the Connector Builder be used to create a connector?
Use a Connector Builder to create a connector when:
- Simplifying 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
