Skip to main content

Connections overview

Learn about connections in Actioner and how to connect your tools.

For an action to communicate with a tool, it has to be authorized to interact with it. This authorization is referred as a connection.

Requests in Actioner are sent to perform actions or to retrieve data for action components. Connections simply enable actions to send API requests to an application.

A connection works as a template for authentication in your tool. You can setup how Actioner sends API requests to your system by adding a connection and entering authentication credentials. Depending on the connection type, the credentials for authentication and authorization can be username/password, an API key or an OAuth2 access token.

Connections are added on app level. They are reusable by all the actions of that app. This means that connections are not tied to a single request or a single action - a connection added to an app can be used by multiple actions.

Note

Slack and HubSpot connections are also used for listening events in your Slack workspace and HubSpot accounts.

Connect your tools​

You can simply add a connection to your app. If your app already contains a connection with your tool, complete connection by authenticating with your credentials.

To add a new connection, go to App settings tab of your app and click + Add new connection. Add new connection

Select connection type from below options and enter a name.

Actioner provides connections to authenticate with the most popular tools. If your tool is not in this list, you can setup a secure connection with Generic basic authentication or Generic API Key options.

Tip

We are actively working on extending our preset connections list. Give us a shout and join our community if you are looking for a connection with your tool.

Authenticate a connection​

Find the connection on Description tab of your app and click Connect. Enter your credentials on the opening screen.

Depending on the authentication type, you will be required to enter base URL, username, password, an API key or a shared access token. If the connection is done via OAuth2, you will need to give authorization to Actioner in your tool. Entering credentials for a connection

Note

If shared credentials option is enabled for a connection, any of the app admins can enter credentials. If this option is disabled, all users in that app need to enter credentials to authenticate the connection.

Info

If you are an app admin, you can update connection properties and complete authentication on App settings tab.

Supported authentication methods​

Actioner connects with your tools through Basic Authentication, API key and OAuth2.

Basic Authentication: is usually the most straightforward and easiest method for connecting to REST APIs by authenticating with a username and password. In a connection with Basic Authentication, Actioner places username:password into the request header every time the connection is called by an API request.

API key: is widely used for authenticating in various applications. In this method, a unique generated value is assigned to each first-time user, signifying that the user is known. Some tools take in API key parameter as sent in the query string, as the part of the URL, while some others accept the API key in the Authorization header. In a API key connection, Actioner sends the configured authentication parameters every time the connection is called by an API request.

OAuth2: is fundamentally considered as a much more secure and powerful authentication method in modern apps. It is used for identifying personal user accounts and granting proper permissions to Actioner. This method matches the login process of a user expects from most modern apps. Authentication of users typically is completed on the app’s own site, allowing you to easily connect accounts without directly entering your account credentials or looking up API keys.

Updating credentials of a connection​

Find the connection on Description tab of your app, click ... ellipsis and select Reconnect. Enter your credentials on the opening screen.

Removing credentials from a connection​

You can unauthorize or delete the connection.

To unauthorize, find the connection on Description tab of your app, click ... ellipsis and select Unauthorize.

A connection can be deleted by an app admin. To delete a connection, find the connection on App settings tab of your app, click ... ellipsis and select Delete.

Sharing scope​

Credentials can be shared for a connection. That is referred to as sharing scope. When Shared credentials option is enabled for a connection, all API requests associated with that connection are sent with the credentials entered by an app admin. When disabled, each user enters their own credentials to execute requests and run actions.

Shared credentials do not mean that connection credentials are exposed to any user. Credentials are used to authenticate requests for the actions that are run by any users in that app. Let's say you have an action that creates deals in HubSpot and the HubSpot connection uses a sales manager's credentials. When create deal action is run by sales reps, all deals will be shown as created by the sales manager even though the sales reps are creating deals.

Tip

To trigger an action through a workflow, API requests are required to be associated with a connection that has Shared credentials option enabled.

Due to the nature of workflows, workflows trigger actions automatically. To be able to run an action automatically, Actioner needs to understand via which users' connection credentials to authenticate the action's requests. Actioner relies on a connection with enabled Shared credentials option to automatically authorize requests with the credentials entered by app admins.

Selecting a connection for an API request​

Associating your requests with a connection is not mandatory in Actioner. You can proceed to sending requests by providing full URLs and setup authorization details such as API key or login credentials in your request's param, headers and body fields. However, sending requests with connections is highly recommended.

There are three important benefits of selecting a connection for your request:

  1. You can re-use the connection's base URL and authentication credentials for any request in your app. This saves you time with not having to enter the same URL or authentication parameters for each request.

  2. OAuth2 authentication: Actioner supports OAuth2 connection with GitHub, Jira, Zendesk, and other popular apps. It is not possible to configure OAuth2 by setting up a request. If you are connecting with GitHub, Jira, Zendesk or other apps we provide OAuth2 option, go to Connections page of your app and add a new connection.

    API Key authentication: To authenticate with an API key in your app, you need to provide a secret private API key in the HTTP headers or URL params. Setting up an API key in the request exposes the API key on request configuration -- meaning that the API key becomes visible to all users with app admin rights.

    Other HTTP authentications such as Basic or Bearer: Similar to API key, you need to provide your login credentials in the HTTP headers or URL params while configuring a Basic or Bearer authentication. This exposes your login credentials on request configuration. The credentials become visible to all app admins.

  3. Connections can be setup with selected sharing scopes. When Shared credentials option is disabled for a connection, each user will need to enter their username/password, API keys or access tokens to execute requests associated with that connection.

Multiple connections in the same app​

It is pretty common to design a set of actions that works across multiple apps. Actioner is flexible in a way to let you add as much connection as you would like.

Connecting two instances of the same tool​

Under the same app, you can add multiple connections from the same tool. As a shortcut, you can clone your existing connection and just update the base URL if necessary and enter credentials to authenticate in the second instance.

Viewing all your connections​

You can see the list of your authenticated connections on Profile page. Go to your profile page from the left menu (click on your profile picture) and navigate to My workspaces tab. Next, expand your workspace.You can see and update your authenticated connections here.

Reconnect to enter your credentials again. Unauthorize to remove your credentials from a connection.

Authenticated connections list

Testing a connection​

You can test a connection once you enter credentials to authenticate. Test requests are sent to the configured test endpoints. For generic connections, you can specify a test URL.

To test a connection, find your connection on App settings tab of your app and click on it. Test by clicking Test connection button at top right corner.

Note

Make sure that base URL is not empty before testing a connection.

Changing the base URL of a connection​

Some apps require different base URLs depending on the data region, or server, or they might use subdomains. In case you want to setup a connection or update an existing one, you can change the base URL.

To update base URL of a connection, find your connection on App settings tab of your app and click on it. Connection detail page opens up. Find Base URL field and enter the new URL.

Connecting to Slack?​

Visit connecting to Slack page to learn how you can connect a Slack workspace.

"User not found" error in Slack​

This error means that your Slack user is not mapped with your Actioner user. This error is thrown when you are registered to Actioner and Slack with different emails.

Visit this page to learn how you can map your user.