X

HTTP:

Home > Function Reference > HTTP

Jump to a Section

  • Authenticate with HTTP Cards

    Overview

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

    Background

    If an prebuilt connector isn’t available, use HTTP 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 HTTP functions, you can create authenticated connections using several HTTP methods:

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

    Authentication Types

    To set up your authentication:

    1. In the Workflows console, select Function > HTTP.
    2. Select an HTTP card.
    3. Click the + New Connection button to open the New Connection dialog.
    4. Enter a nickname for your connection. Since the HTTP 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 HTTP 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.
      • 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.

    Note: Connections are not tested automatically in the HTTP cards as they are when using prebuilt connector. To test your connection, use the Test this card functionality in a flow.

  • Close

    For use with API Endpoint Flows only. This function sends a response back to the caller and closes the HTTP connection, similar to Return or Return Raw, but also allows the Flow to continue execution afterward. This is useful for Flows that might not complete before the connection times out, after which the caller might call the endpoint again with the same inputs (thus causing unintended duplicate executions).

    Input Fields

    • statusCode (Number): the status code to return to the caller.  A regular Return card would typically return the code 200. Valid values are:  200, 400-600.
    • headers (Custom): Create a field for each key/value pair you want to include in the response header (e.g. a field called “Content-Type” with the value “text/plain”. You can create fields by clicking and then specifying a name and type, or by dragging-and-dropping outputs from other cards.
    • body (Custom): Similar to a Return card, create a field for each value that needs to be returned to the caller. You can create fields by clicking and then giving a name and type, or by dragging-and-dropping outputs from other cards.

    Output Fields

    No output fields.

  • Delete

    Overview

    Performs an HTTP DELETE request, returning the result of this request and the response headers. On input, takes a required URL input and optional header, body, and query inputs.

    Input Fields

    • URL (text): required URL for HTTP DELETE request
    • headers (Section): If required for the HTTP DELETE request to the specified URL, create headers by specifying an input name equal to the key (e.g. “Content-Type”) and then specifying a value for the input (e.g. “application/json”). Information on headers required for your HTTP DELETE request should be specified by the provider of the URL.
    • query (Section): If necessary for the HTTP DELETE request to the specified URL, create query string parameters by specifying an input name equal to the key (e.g. “page”) and then specifying a value for the input (e.g. “1”). Information on the query string parameters available for your HTTP DELETE request should be specified by the provider of the URL.
    • body (Section): If required for the HTTP DELETE request to the specified URL, create a request body by specifying an input name equal to the key (e.g. “id”) and then specifying a value for the input (e.g. “123”). Information on the request body required for your HTTP DELETE request should be specified by the provider of the URL.

    Output Fields

    • statusCode (Number): the status (200, 404, etc) associated with the DELETE request
    • body (Section): using syntax similar to the outputs for Get Multiple, specify optional paths that allow retrieving values from the response body
    • headers (Section): specify optional keys that allow retrieving values from the response headers

  • Get

    Overview

    Performs an HTTP GET request, returning the result of this request and the response headers. On input, takes a required URL input and optional auth, header, and query inputs. Each optional input can either be modeled by a singular object-typed input or by multiple keys with the appropriate group attribute. On output, returns an object with two keys, headers and output. The output key contains the response body, and the headers key contains the response header. More detailed information can be accessed about these by using multiple keys with the appropriate grouping. NOTE:

    • If you are looking to submit data to a URL and then get data back, use the POST card instead as GET does not allow for body inputs.
    • The ‘Content-Type’ header is implicitly set to ‘application/json’ for all HTTP functions (excluding Raw Request).

    Input Fields

    • URL (text): required URL for HTTP GET request
    • headers (Section): If required for the HTTP GET request to the specified URL, create headers by specifying an input name equal to the key (e.g. “Authentication”) and then specifying a value for the input. Information on headers required for your HTTP GET request should be specified by the provider of the URL.
    • query (Section): If necessary for the HTTP GET request to the specified URL, create query string parameters by specifying an input name equal to the key (e.g. “page”) and then specifying a value for the input (e.g. “1”). Information on the query string parameters available for your HTTP GET request should be specified by the provider of the URL.

    Output Fields

    • statusCode (Number): the status (200, 404, etc) associated with the GET request
    • body (Section): using syntax similar to the outputs for Get Multiple, specify optional paths that allow retrieving values from the response body directly on the HTTP GET action without using additional functions
    • headers (Section): specify optional keys that allow retrieving values from the response headers directly on the HTTP GET action without using additional functions

  • Post

    Overview

    Performs an HTTP POST request, returning the result of this request and the response headers. On input, takes a required URL input and optional auth, header, body, and query inputs. Each optional input can either be modeled by a singular object-typed input or by multiple keys with the appropriate group attribute. On output, returns an object with two keys, headers and output. The output key contains the response body, and the headers key contains the response header. More detailed information can be accessed about these by using multiple keys with the appropriate grouping.

    Input Fields

    • URL (text): required URL for HTTP POST request
    • headers (Section): If required for the HTTP POST request to the specified URL, create headers by specifying an input name equal to the key (e.g. “Content-Type”) and then specifying a value for the input (e.g. “application/json”). Information on headers required for your HTTP POST request should be specified by the provider of the URL.
    • query (Section): If necessary for the HTTP POST request to the specified URL, create query string parameters by specifying an input name equal to the key (e.g. “page”) and then specifying a value for the input (e.g. “1”). Information on the query string parameters available for your HTTP POST request should be specified by the provider of the URL.
    • body (Section): If required for the HTTP POST request to the specified URL, create a request body by specifying an input name equal to the key (e.g. “id”) and then specifying a value for the input (e.g. “123”). Information on the request body required for your HTTP POST request should be specified by the provider of the URL.

    Output Fields

    • statusCode (Number): the status (200, 404, etc) associated with the POST request
    • body (Section): using syntax similar to the outputs for Get Multiple, specify optional paths that allow retrieving values from the response body
    • headers (Section): specify optional keys that allow retrieving values from the response headers

  • Put

    Overview

    Performs an HTTP PUT request, returning the result of this request and the response headers. On input, takes a required URL input and optional auth, header, body, and query inputs. Each optional input can either be modeled by a singular object-typed input or by multiple keys with the appropriate group attribute. On output, returns an object with two keys, headers and output. The output key contains the response body, and the headers key contains the response header. More detailed information can be accessed about these by using multiple keys with the appropriate grouping.

    Input Fields

    • URL (text): required URL for HTTP PUT request
    • headers (Section): If required for the HTTP PUT request to the specified URL, create headers by specifying an input name equal to the key (e.g. “Content-Type”) and then specifying a value for the input (e.g. “application/json”). Information on headers required for your HTTP PUT request should be specified by the provider of the URL.
    • query (Section): If necessary for the HTTP PUT request to the specified URL, create query string parameters by specifying an input name equal to the key (e.g. “page”) and then specifying a value for the input (e.g. “1”). Information on the query string parameters available for your HTTP PUT request should be specified by the provider of the URL.
    • body (Section): If required for the HTTP PUT request to the specified URL, create a request body by specifying an input name equal to the key (e.g. “id”) and then specifying a value for the input (e.g. “123”). Information on the request body required for your HTTP PUT request should be specified by the provider of the URL.

    Output Fields

    • statusCode (Number): the status (200, 404, etc) associated with the PUT request
    • body (Section): using syntax similar to the outputs for Get Multiple, specify optional paths that allow retrieving values from the response body
    • headers (Section): specify optional keys that allow retrieving values from the response headers

  • Raw Request

    Overview

    Advanced.  This method performs a raw HTTP request, allowing the Flow builder to control all aspects of the HTTP request.  This allows a Flow to call an XML service for example, or call an HTML service, or a number of other advanced usages.  The other HTTP functions are optimized for ease-of-use with typical JSON-based services; the Raw Request function is more flexible, at the cost of being a bit harder to use. Here are a few of the use cases for Raw Request:

    • Call an XML service:  use the XML Build function to create an XML string containing your request and drag that into the body input of Raw Request.  Then use the XML Parse function to parse the body output, to create a JSON response that you can then use in the rest of your Flow.  Works equally well with an HTML service, etc.
    • Call a JSON API with a list:  The HTTP Post function implicitly forces you to pass a JSON object in the body - each input you create in the body section becomes a key in the request body.  If you want something else - such as passing a list of objects rather than an object - you can do that using Raw Request by simply building the list you want using the List functions, then calling JSON Stringify to create a string, then dragging that string into the body input of Raw Request.
    • Build a query programmatically:  You may have logic that determines your query string at runtime.  Use the Object functions - Object.Construct, Object.Set, etc - to create a query object in your Flow, then drag your object to the query input of Raw Request.  The query object will convert to the URL query string like this - if your query object is { “x”: “one”, “y”: “two”} then the query string will be:  ?x=one&y=two
    • Build headers programmatically:  Similar to the above, the other HTTP functions implicitly force you to define your header field names at design time - the values can be dynamic, but the header field names are fixed. If you want do define them in the Flow, use the Object functions - Object.Construct, Object.Set, etc - to create a headers object in your Flow, then drag your object to the headers input of Raw Request.  For example if the headers object is { “Accept”: “text/plain” } then the header string for the request would be “Accept: text/plain”.
    • Call a JSON API with dynamic keys:  Similar to the above, the HTTP Post function implicitly forces you to create the keys in the request body at design time, i.e. when you are building the Flow.  If you want to build this at runtime, based on input parameters for example, you can do so build building the object using the Object functions, passing that to the JSON Stringify function, then dragging that string into the body input of Raw Request.

    The Raw Request function is flexible enough to form any HTTP call - if the other HTTP functions don’t have the flexibility you need, try this one instead.

    Input Fields

    • URL (text): required.  The URL for the request
    • method (dropdown): Select one of the http methods:  GET, POST, PUT, PATCH, DELETE
    • headers (Object): An object representing the headers for the request.  Each key of the header will be parsed into a header string as ”key: value”, i.e. “Accept: text/plain”
    • query (Object): An object representing the URL query string.  Each key of the header will be appended to the URL string as follows:  url?key1=value1&key2=value2&…
    • body (text): The http request body.

    Output Fields

    • statusCode (Number): the status code (200, 404, etc) returned by the service
    • headers (Object): An object representing the http response headers, in the same format as the input headers object.
    • body (text): the http response.