Authenticate with API Connector cards

Overview

Use API Connector function cards to make authenticated connections to third-party services.

Background

If a pre-built connector isn't available, you can use API Connector cards to make a request to a third-party service and then parse the response in your flow. Your credentials are stored securely, and a header is created automatically using one of the provided authentication types.

HTTP Methods

With the API Connector functions, you can create authenticated connections using any one of the listed HTTP methods. The following methods perform the specified type of request and return the result of the request and the response headers:

• Delete
• Get
• Patch
• Post
• Put

The Close and Raw Request methods differ slightly from the previous methods, as described:

• Close: Sends a response to the caller and then closes the HTTP connection. Use this function when the caller doesn't need to wait for the flow to complete, or when you need to avoid a connection timeout.
• Raw Request: Performs a raw HTTP request, with complete control over the request and the response. This is useful for calling XML services and for other advanced HTTP use cases.

Authentication Types

Follow these steps to set up your authentication:

1. In the Flow builder, select FunctionAPI Connector.

2. Select an API Connector card.

3. Click the + New Connection button to open the New Connection dialog.

4. Enter a nickname for your connection.

   Since the API Connector cards can be used with multiple connections, enter a detailed name to distinguish each connection.

   Describe the service being called, the type of authentication, and a reference to the account being used. For example, JIRA Service Management - OAuth - service_account.

5. Select your authentication type from the dropdown list. The API Connector cards support the following authentication types: Basic, Custom Header, OAuth, Client Credentials, or None. See Authentication Types.

6. Enter the requested values required for your authentication type.

7. Click Create.

Authentication type options

Basic

A simple authentication scheme built into the HTTP protocol. The required values are the Username and Password for the third-party application being called.

Okta Workflows sends HTTP requests with an authorization header containing the word Basic followed by a space and a base64 encoded string of <username>:<password>.

OAuth

OAuth 2.0 is a protocol that allows you to grant scoped access to resources on a third-party site and doesn't expose your credentials. Before beginning the OAuth process, you must first register a new app with the service including information such as the application name and website URL.

In addition, you must register a redirect URI to be used for redirecting authentication back to Workflows. Use the following redirect URIs to connect to Okta Workflows preview and production orgs, respectively: https://oauth.workflows.oktapreview.com/oauth/httpfunctions/cb and https://oauth.workflows.okta.com/oauth/httpfunctions/cb.

• Authorize Path: The authorization path for the service. For example, https://example.com/oauth2/v1/authorize.

  If your OAuth implementation requires other query parameters, you can add them here. Follow the authorization path with the ? character, and then add your parameters as key=value pairs separated by the & character.

• Access Token Path: The URI where Workflows can exchange an authorization code for access and refresh tokens.

• Scope: Specifies the level of access provided to Workflows. You can enter multiple scopes separated with spaces or commas, but this depends on the service. Check the API documentation for your service to see if any special scopes are needed to retrieve a refresh token (such as refresh_token or offline_access).

• Client ID: A publicly exposed string provided by the service that identifies the OAuth application and is used to build authorization URLs.

• Client Secret: A private value provided by the service that authenticates the identity of the application to the service.

Client Credentials

Client Credentials is a grant type of the OAuth 2.0 protocol. This allows you to grant full and non-user specific access to third-party resources. As with the OAuth option, you must first register a new app with the service including information such as the application name and website URL.

• Access Token Path: The URI where Workflows can exchange an authorization code for access and refresh tokens. For example, https://example.com/oauth2/v1/token.

• Client ID: A publicly exposed string provided by the service that identifies the OAuth application and is used to build authorization URLs.

• Client Secret: A private value provided by the service that authenticates the identity of the application to the service.

Credentials are sent in the request body and not as a Basic authorization header.

Custom

This option allows you to create a custom header name and value.

• Header Name: a custom name to be passed to the service. For example, a service may require api_key as the header name and the key itself as the value.

• Header Value: the value to be passed to the service along with the header name.

None

Use this option to manually create your connection when none of the other options apply. It can also be used to access unauthenticated endpoints.