Authenticate with API Connector cards

Overview

Use API Connector function cards to make authenticated basic, OAuth 2, or custom connections to third party services.

Background

If a prebuilt connector isn't available, use API Connector cards to make a request to a third-party service and 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 several HTTP methods:

• Raw Request
• Close
• Delete
• Get
• Post
• Put
• Patch

Authentication Types

To set up your authentication:

1. In the Workflows console, select Function > API 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, it is best practice to enter a detailed name to distinguish each connection that includes the service being called, the type of authentication, and a reference to the account being used. "JIRA Service Desk - OAuth - serviceaccount", for example.

5. Select your Auth Type from the dropdown. The API Connector cards support three types of authentication out of the box: Basic, OAuth, and Custom Header.

6. Populate the requested values depending on your Auth Type selection.

7. Click Create.

The fields for each type are listed below.

• Basic: Simple user name and password scheme built into the HTTP protocol. Workflows sends HTTP requests with the Authorization header containing the word Basic followed by a space and a base64 encoded string of "username:password".

  • Username: username for the third-party application

  • Password: password for the third-party application

• OAuth: OAuth 2.0 is a protocol that allows you to grant limited access to resources on a third party site without having to expose your credentials to Workflows. Before beginning the OAuth process, you must first register a new app with the service. When registering a new app, you usually register basic information such as application name, website, etc. 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 Prod 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.

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

  • Scope: specifies the level of access provided to Workflows. Multiple scopes are often space or comma separated, but this can depend on the service. To verify whether a special scope is needed to retrieve a refresh token (such as refresh_token or offline_access), see your API documentation.

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

  • Client Secret: a private value provided by the service used to authenticate the identity of the application to the service

• Custom: Selecting Custom Header 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.