Connections

Connections represent credentials and configuration used to access integrations on behalf of your customers.

They have the following properties:

Creating Connections

We recommend using Connection UI implemented with our drop-in components or Javascript SDK.
Use the flow below only when you know what you are doing.

To create a new connection or refresh credentials for an existing connection, follow the steps described below.
They work in the same way for every connector regardless of the app that is being connected.

Connector Auth Spec

You can get information about how authentication works in a given connector from its specification. Look for the following fields:

• auth.type - type of authentication supported by the connector. Possible values are:
  • client-credentials - Authentication based on credentials user enters in the UI.
  • oauth1 - OAuth1 authentication
  • oauth2 - OAuth2 authentication
• ui - information about what to display user in the UI when authenticating.

Authentication Flow

To authenticate a user you need to do the following:

1. Collect connection parameters from the user. They need to match ui.schema.
2. Redirect user to https://api.integration.app/connection-popup URL with the parameters described below. If auth.type is client-credentials, you can open this URL in a hidden iframe. If not, you need to open it in a new window visible to the user.

Add the following query parameters to the URL:

• token - your customer's Access Token
• requestId - a unique id of this authentication request. It will be used in the callback to separate callbacks from different requests. Note: providing this parameter will result in window being closed after connection is created. If you want it to behave differently (for example, redirect to another URL), you cannot use this parameter.
• integrationKey - key of the integration you want to authenticate against.
• connectionId (optional) - id of the connection you want to refresh credentials for (if you want to do it for a specific connection)
• connectionParameters (optional) - parameters provided by user in the connection UI, JSON-encoded.

Custom Callback URL

In some cases you need to use a custom Callback URL instead of standard https://api.integration.app/oauth-callback. These situations include:

• When you need to approve your app and callback URL needs to be on your domain (for example, Google requires that).
• You want to create a custom installation logic for some application stores (for example, Pipedrive app installation flow).
• When you want to do any other custom handling of oAuth callback.

You can set custom callback URI in the integration settings. It will be used for all connections created for this integration.

After handling the callback URI, you need to redirect user to https://api.integration.app/oauth-callback URL with the same query parameters you received in the callback URI.

For example, if you use callback url https://myapp.com/oauth-callback and a third-party application sends user to the following URL:

https://myapp.com/oauth-callback?code=abcd&state=1234

when you are done with the user, you need to redirect them to:

https://api.integration.app/oauth-callback?code=abcd&state=1234

Custom State

For OAuth2 connections, you can add a custom component to the state parameter used in the callback URI. This can be useful if you want to pass some information through the authentication process.

To do this, simply add customState query parameter when opening the https://api.integration.app/connection-popup URL like this:

https://api.integration.app/connection-popup?customState=MY_CUSTOM_STATE

When the user is redirected to the callback URI, the state parameter will contain the value of customState parameter after : symbol like this:

https://myapp.com/oauth-callback?code=abcd&state=1234:MY_CUSTOM_STATE

Auth from outside of integration.app

When connection is initiated outside of integration.app (for example, from an app store of a third-party application),
you need to add the following additional query parameters when redirecting user to integration.app:

• token is Integration.app Token you normally use to access our API or SDK.
• integration is id or key of the integration you want to authenticate against (i.e. hubspot or salesforce).
• redirectUri is the URL you want to redirect user to after connection is created. This could be a page in your app you want the user to end up on.

For example, if you use callback url https://myapp.com/oauth-callback and a third-party application sends user to the following URL:

https://myapp.com/oauth-callback?code=abcd

when you are done with the user, you need to redirect them to:

https://api.integration.app/oauth-callback?integration=pipedrive&code=abcd&token=AUTH_TOKEN&redirectUri=https://myapp.com/configure-integration

After user's connection is successfully created by integration.app, the user will be redirected to https://myapp.com/configure-integration URL.
If redirectUri is not provided, integration.app will simply close the window after connection is successfully created.

If connection creation fails, user will be redirected to your redirectUri with error parameter like this:

https://myapp.com/configure-integration?error=ERROR_MESSAGE

Secrets

credentials, parameters, and connectorParameters are encrypted at rest and are not returned with the connection object by default.

To get these values, you should add includeSecrets=true to the query parameters of your request to get a single connection.
This request must be made using workspace admin access token.