Set up a token-based HTTP connection

Token-based authentication is stateless, which means that neither the server nor the session stores any information about the user. The token is sent on every request, helping to prevent cross-site request forgery attacks. For added security the token expires after a set amount of time.

You can build integrations with apps that use HTTP even if the connection is not already provided by Celigo integrator.io.

Before creating the connection, review your app’s API guide. It should provide the information you need, such as the kind of authentication that the app requires and its URI.

Contents

• A. Create the HTTP connection
• B. Name the connection and choose its mode
• C. Describe the connection
• D. Configure token authentication
• E. Edit common HTTP settings (optional)
• F. Save, test, and authorize

A. Create the HTTP connection

1. Sign in to integrator.io.
2. From the Tools menu, click Flow Builder.
3. When exporting data from this app, click Add source.
   – or –
   When importing data into this app, click Add destination/lookup.
4. Click HTTP from the list of application types.
5. Next to Connection, click the create icon.

B. Name the connection and choose its mode

Note: For on-premise mode, an agent must first be installed and configured. If the system you want to connect to is behind a firewall, the agent helps connect without having to whitelist any IPs.

Name (required): Give your connection a name that is meaningful to your integration and that can help you identify it later in a list of connections.

Mode (required): Choose one of the following:

• Cloud: Connect to an app in the cloud.
• On-premise: Connect to an an on-premise app, which runs locally on the company’s servers.
  From the Agent dropdown, select an installed agent.

C. Describe the connection

Provide the application details.

Configure HTTP headers (optional): Click this button to pass additional parameters in the header. Configure any headers as needed for your integration, providing the names and values in the resulting editor.

Base URI (required): Enter the base URI, which is the path to the app’s API, as documented in the API guide.

Media type (required): Choose the format for your records.

• Success media type (optional): Select the type of content expected when a response succeeds (such as XML or JSON).
• Error media type (optional): Select the type of content expected when an error occurs.

D. Configure token authentication

Enter the token details.

Authentication type (required): Select Token.

Token (required): Enter your API token. Multiple layers of protection (including AES 256 encryption) are in place to secure your API token.

Location (required): Referring to the app's API documentation, select where the API expects to find the authentication token. Additional options may appear specific to that location:

• URL Parameter
  
  Parameter name (required): Enter the name of the URL parameter that holds the API token value. For example, if you enter myAPITokenURLParam, then all HTTP requests will include
  ?myAPITokenURLParam=[token].
  
  
• Header
  
  Header name (optional): By default, integrator.io will send all authentication info in the authorization HTTP header field. If the application you are connecting to requires a different HTTP header, enter the name here.
  Scheme (required): Select an authentication scheme, per the API documentation.
  If the API you are connecting to doesn't follow the HTTP specs for the authentication scheme exactly, select Custom and enter a Custom auth scheme.
  
  
• Body

Configure token refresh(optional): Check this box if your token expires after a period of time. Then, configure the additional options that appear.

Authentication fail status code (optional): Enter the status code if the service you are connecting to returns a status code other than 401 or returns 200 with authentication errors in the HTTP body.

Authentication fail path (optional): Specify the path if the service you are connecting to embeds authentication errors in the HTTP body. integrator.io uses these values to identify a failed authentication response.

Authentication fail values (optional): Enter the appropriate values if the authentication fail path is set. integrator.io uses these values to recognize a failed authentication response.

E. Edit common HTTP settings (optional)

If needed, configure the settings in the additional sections:

• Nonstandard API rate limiter
• How to test connection?
• Advanced

For complete documentation of these settings, see Fundamentals of HTTP connections.

F. 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 theCreate connectionpane
• Cancel – 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.