Custom HTTP authentication type might prove useful when you need to send a secret key (such as a password or authKey) as part of the URI, header, or post body to communicate with an endpoint.
Before creating the connection, review your app’s API guide. It will provide the information you need, such as the kind of authentication that the app requires and its URI. Every app puts its documentation – guides and reference material – in different places. You can often find it by searching for “API guide” or “API documentation” on the company’s website.
A. Set up an HTTP connection
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.
B. Provide general HTTP connection settings
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.
C. Edit custom auth settings
Continuing in the Create connection panel, select Custom for the Auth type. The settings then become specific to custom auth:
Custom encrypted fields (optional): Store all sensitive fields required by your imports and exports to access the app you are connecting to. Click the Expand window ( 
) button to modify the JSON sent to the app in the Encrypted Advanced Field Editor. For example, enter {"secretKey": "someSecretKeyValue"}. (You can also retrieve these sensitive values elsewhere, such as How to test this connection?, via the example handlebars format {{{connection.http.encrypted.secretKey}}}.) Multiple layers of protection are in place, including AES 256 encryption, to keep your connection’s encrypted fields safe. When editing this form later, you must enter this value again; it is stored only when the connection is saved and never displayed as text.
Custom unencrypted fields (optional): Store all non-sensitive fields required by your imports and exports to access the app you are connecting to. Click the Expand window ( ) button to modify the JSON sent to the app in the Advanced Field Editor. For example, enter {'email':'my_email@company.com', 'accountId': '8675301', 'role':'admin'}. (You can also retrieve these values elsewhere, such as How to test this connection?, via the example handlebars format {{{connection.http.unencrypted.accountId}}}.)
Configure refresh token (optional): Select the check box if you want to configure the refresh token. For configuration details, see Configure refresh token.
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.
Configure refresh token
Refresh token (required): Enter a token that can serve as a refresh expired auth token.
You can place this token in the body, headers or URL simply by referencing it with the handlebars placeholder {{connection.http.auth.token.refreshToken}}. Multiple layers of protection, including AES 256 encryption, are in place to keep your token safe. When editing this connection, you must re-enter this value each time; it is stored only when the connection is saved and never displayed as text.
HTTP method (required): If the service you’re connecting to supports token request/refresh, select the HTTP method to use in the token call. When you select POST, the setting HTTP request body is revealed, below.
Relative URI (optional): If the service you’re connecting to supports requests to obtain or refresh existing tokens, enter the URL (relative to the base URI) to use in the request token call. Click the handlebars (
) button to open the Advanced field editor and create or edit a template. Note that handlebars placeholders, such as {{connection.http.encrypted.password}}, may be used to reference any connection fields. Typically, a username/password or refresh token is required in the request, which you can store in the encrypted field or, if not sensitive, the unencrypted field.
Note: If the API you are connecting to uses a completely different URL to obtain or refresh existing tokens (instead of a relative URL), enter the full absolute URL including the HTTP prefix: http(s)://fullTokenRefreshURL.
Configure HTTP headers (optional): In some cases, it may be necessary to include custom HTTP headers with your token refresh requests. You can reference dynamic path field names for the connection using handlebars {{placeholders}}.
Override media type (optional): When the HTTP request requires a different media type than what is configured on the connection, select an alternate value.
HTTP request body (optional, enabled when HTTP method is POST): If the service you’re connecting to supports requests to obtain or refresh existing tokens, enter the body to use in the request token call. Click the handlebars () button to open the Advanced field editor and create or edit a template. You may also use handlebars placeholders to reference any connection fields. Typically, a username/password or refresh token would be passed in the request. You can store these values in the encrypted field or, if not sensitive, the unencrypted field. For example, {{connection.http.encrypted.password}}.
Path to token field in HTTP response body (optional): If the service you’re connecting to supports requests to obtain or refresh tokens, enter the path contained in the HTTP response where the new token can be extracted. If no value is found at this path, then the token request is considered a failure.
Paths to encrypted field in the HTTP response body (optional): If the service you’re connecting to responds with more than one encrypted field containing refresh tokens, then enter the JSON paths contained in the HTTP response where the new tokens can be extracted. Separate multiple fields with a comma. If no values are found in these paths, then the token request is considered a failure.
D. Edit common HTTP settings
Additional HTTP settings are found in the other sections in the Create connection panel (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?
- Advanced
For complete documentation of these settings, see Fundamentals of HTTP connections.
E. Save, test, and authorize
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.
Comments
Please sign in to leave a comment.