Tray Platform / Using Connectors / Authenticating Connectors

Authenticating Connectors

Just as when you log into your Gmail, Facebook, Salesforce, LinkedIn account etc., any service connectors you wish to use also require an authentication to verify the user.

Authentications can be built and used within these three areas:

  1. Personal - Used only by you.

  2. Organization - For example a company login used by anyone within your organisation.

  3. Workspace - Sub-divisions of your organisation.

USER TIP: Please see the Managing Authentications page for guidance on how best to handle authentications within your organization and instructions on creating authentications from the dashboard.

Read on for an overview of the different types of authentications you will come across.

Then you can go to the Service Connectors own page to find the specific instructions needed in order to authenticate.

Naming your Authentications

Please take care when naming your authentications.

You will often need to create more than one over time (even for the same services) and it can become incredibly easy to get them confused with one another if you don't take your naming conventions seriously.

You should try to name your authentications in a way that will quickly identify it within a potentially large list. Consider who/ how many people will need access to this authentication when choosing where to create this authentication

For example whether it is a Sandbox or Production auth. Maybe including the name of the service API version you are using would be useful. Perhaps you could specify the Workspace group or Organisation associated with this particular type of authentication so you know if its one you and your team have access to.

If you take the above into account upon creation when looking in your group of available authentications later on finding the right one will be simple!

Building your Auths

There are two main areas that you can build your service authentications from.

PLEASE NOTE: Please bear in mind that the HTTP connector has an extra feature due to its unique capabilities. Users are able to build a custom service authentication from the authentication popup modal. For more details please head to the HTTP documentation page.

Workflow

Once you are within the builder highlight the connector you want to create a new authentication for.

In the connector properties panel select the Auth tab and the New authentication button.

auth-new-1
auth-new-2

Dashboard

Within the main Tray.io dashboard click on the Authentications section. Click Create new authentication.

auth-new-3

Here you will have two options. Do you want to authenticate with a prebuilt service or connect to a custom API:

auth-new-5
auth-new-4

Auth types

Token based

Some API's prefer to use Bearer Tokens as a means for validation. Such as Airtable.

All you need do is add your token to the form when the property is presented:

airtable-auth-new-token-eg

OAuth2

APIs that use OAuth or OAuth2 display a more complex box. From here you can reduce the permission 'scopes'.

Be careful - reducing the scopes might prevent the connector from functioning properly (required scopes are described in individual connector docs).

Please take note that every connector authentication window is unique! There are many variables involved that are dependant on the service's own requirements and API calls.

Individual service connector documentation gives more specific details on how to set up a connector's authentication.

oath2-scopes-gif

PLEASE NOTE: Tray does support OAuth (or OAuth 1) authentications, we simply don't recommend them due to the security risk they might impose.

Certificate-based Authentication

Tray can also support certificate-based authentications. Please contact us if you need a custom certificate-based authentication built for your service.

Creating new Services

If you need to connect to a third party service (for when there is no pre-existing Tray.io connector) there are three ways in which you can do this:

  1. Generic Service Authentication - HTTP client only (token based)

  2. Create a new service and auth (via the HTTP client or authentications dashboard)

  3. Create a new service only (for which authentications can later be made)

You cannot use Generic Service Authentication with complex token-based and Oauth-based authentications. In such cases, we recommend creating a new service.

Consider a scenario where you want to launch a modal in slack when a /test-referral command is fired in Slack. To launch the modal you need to use an HTTP Client connector.

launch-initial-modal

To authenticate the HTTP Client with the required Slack app you can use the Generic Service authentication method.

For security purposes, be careful when you create a Generic service auth in an organization workspace as it will be accessible to everyone in your organisation.

Generic Service Authentication

Create a Service & Auth

There are essentially two routes for doing this.

  • Go to your Personal workspace and select the main Tray.io Authentications tab. Click 'Create new authentication'.

    • Note that you will not be able to create an authentication AND a service at the same time within any other workspace.

  • The other route is via the HTTP connector within the builder itself.

    • See the Custom Services page for more details on what can be done with the HTTP connector.

Create a Service only

To reference a service when creating an authentication with the HTTP Client you can for example, choose a name for your auth token and then enter the actual token value.

This auth token can then be used in your API call (for example, as a parameter) by including the path $.auth.token_name.

Please see the Custom Services guide for an illustration of how this generic approach works.