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 pre-built 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, enter a detailed name to distinguish each connection. Include 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 three types of authentication out of the box: Basic, OAuth, and Custom Header.

  6. Populate the requested values depending on your authentication type selection.

  7. Click Create.

Authentication type options
  • Basic: A simple username and password scheme built into the HTTP protocol. Okta 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: the username for the third-party application.

    • Password: the 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. 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 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.

    • 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: 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.

Unlike pre-built connectors, connections aren't tested automatically in the API Connector cards. To test your connection, use the Test this card functionality in a flow.