Tip: Some companies put their documentation on third-party sites. If you can’t find the guide on their website, you can also try a web search.
Some APIs authorize calls and maintain session information by responding to a cookie request, which is sent back in a set-cookie response header. Cookie authentication is vulnerable to cross-site request forgery (CSRF) attacks and should be used with other security measures, such as CSRF tokens.
- A. Set up an HTTP connection
- B. Provide general HTTP connection settings
- C. Edit cookie auth settings
- D. Edit common HTTP settings
- E. Save, test, and authorize
Start establishing the universal, or generic, HTTP connection in either of the following ways:
- Select Connections from the Resources menu.
- Next, click + Create connection at the top right. In the resulting Create source panel, select HTTP from the Application list, under the Universal connectors group.
- While working in a new or existing integration, you can add an application to a flow simply by clicking Add source or Add destination/lookup. From the Application list, under Universal connectors, select HTTP.
- After the HTTP Application is added, click the Connection setting’s + button to proceed.
Name (required): Provide a clear and distinguishable name. Throughout integrator.io imports and exports, you will have the option to choose this new connection, and a unique identifier will prove helpful later when selecting among a list of connections that you’ve created.
Application (required, non-editable): A reminder of the app you’re editing.
Mode (required): Select one of the following options:
- Cloud to connect to a publicly accessible server application
- On-premise to connect to a server that is publicly inaccessible and has integrator.io agent installed on it
Agent (required, if On-premise selected for Mode; otherwise not displayed): Select an agent from the list. To connect to an on-premise application, integrator.io requires that an agent be installed on a networked computer. An agent is a small application that allows you to connect to data behind your firewall. When installing an agent, you will specify a unique access token, which then populates the Agent drop-down list. The installed agents connect to integrator.io and establish a reverse SSH tunnel, allowing secure communication without the need to whitelist integrator.io IP addresses in your firewall settings. A single agent can be used by multiple different connections.
Continuing in the Create connection pane, select Cookie for the Authentication type. The settings then become specific to cookie-based connections:
HTTP method (required): Select GET or POST, depending on the API requirements for making a request for the cookie.
HTTP request body (enabled and required when HTTP method is POST): Enter the body that will be posted to the URI endpoint. Click the handlebars button () to open the Advanced field editor and create or edit a template. You may reference any fields in your connection or flow's data within handlebars
Absolute URL (required): Enter the endpoint that integrator.io will use to make the cookie authorization request. Click the handlebars button () to open the Advanced field editor and create or edit a template. You may reference any fields in your connection or flow's data inside handlebars
Override HTTP status code for success (optional): If the application returns any success status code other than 200, enter the expected value.
Override HTTP status code for auth errors (optional): Provide an alternate status code if the HTTP status code for auth errors returned by this app is not the standard 401. For example, for an API that returns a generic 400 status code, enter 400 and then specify the field in the HTTP response body that indicates auth errors.
Path to auth error field in HTTP response body (optional): If the API returns a field that contains auth errors in the HTTP response body, enter the JSON path to that field. For example, when an API returns the field
errorMessage with the value
Auth failed, then enter
errorMessage as the path.
Auth error values (optional): If you supplied a fail path above, enter the exact values that the API will return to indicate auth errors. Separate multiple values with commas.
Additional HTTP settings are found in the other sections in the Create connection pane (optional sections are collapsed by default):
- Application details (contains the required settings Base URI and Media type)
- Nonstandard API rate limiter
- How to test this connection?
For complete documentation of these settings, see Fundamentals of HTTP connections.
Once you have configured the HTTP connection, you have a few options for continuing:
- Save – click this button to test the connection, commit the new connection so that it will be available to all integrations for your account
- Save & close – click to test and save the connection and exit the Create connection pane
- Close – click to exit without saving any new changes
- Test connection – click this button to verify that your new connection is free of errors
When you test or save the connection, it is verified before continuing.
If the connection fails, double-check the provided settings, and test again.