Tray Platform / Using Connectors / Custom services

Custom services

Overview

When you are wanting to use a service which is not available in the list of pre-built Tray connectors, you will need to build a custom service.

You may also find that some Tray connectors do not work with a particular endpoint that you want to access.

For example you may already have used the Slack connector to e.g send messages, but there is a particular Slack API endpoint you want to work with, that is not accessed by any of our Slack connector operations.

In either case you can go to the Services tab in your Personal Workspace and create a custom service:

Once you have built a custom service, you can then use the Http Client to make all the calls you need to the service.

This page takes you through the basic steps involved in building a custom service. Please see our Http Client documentation for more details on making calls to custom services you have created

Creating a service

IMPORTANT!: Custom services can only be created in a personal workspace.

They are then available organization-wide.

We also strongly recommend you create a single User Account exclusively for creating custom services.

The login details for this account should then be given to anyone who needs to create them.

This means you will not be at risk of a person leaving your company and denying access to services created in their workspace.

This also makes general management and deletion of custom services a lot easier to handle

Reading API documentation

In order to work out how to authenticate with your service and how to make specific calls to e.g. a '/customers' or a '/accounts' enpdoint you will need to read the API documentation published for that service.

Please note that there is no uniform standardization of language or terminology across all potential services.

If you are new to reading API documentation, we highly recommend you check out our 'Reading API docs' Academy course

All service API documentation is written in a style specific to that company. When used in conjunction with our own, the terminology can get confusing.

For example, when Tray.io refers to a 'parameter' within the context of a custom service, it refers to it in the form of a 'query parameter'. Another service may use the same term to refer to a 'header parameter' or item in the 'request body'.

Another example worthy of note is that a service within Tray.io usually refers to a service connector, such as the AWS connectors.

However, a lot of documentation will have a general commonality and therefore should not be too difficult to comprehend.

Remember that you can also check out service forums and examples of what users before you tried to do online.

Authentication methods

There are three main methods of authenticating with the HTTP client connector: OAuth2, Token and Pre-existing.

IMPORTANT!: While it is possible to also authenticate with OAuth1 and SOAP authentications, we do not recommend this unless absolutely necessary due to the security risks they pose.

You can find a basic setup guide for the three methods in the various subsections below.

For more detailed walk-throughs, look to our Authentication examples at the bottom which uses specific examples to demonstrate the full process.

OAuth2

To enable OAuth2 based authentication for this connector, you'll need to create an "app" with the third party service.

This will require you to have access to the client ID, client secret, authentication URL and access token URL of your third party service as a bare minimum.

Please follow the steps as displayed where possible, for your own chosen OAuth2 based API authentication service.

For those looking for a more detailed walk-through, checkout our OAuth2 example: Authentication examples: OAuth2: Spotify

Token-based

To enable Token based authentication, you'll need access to the token of the third-party service you wish to use, as well as knowledge of any additional properties needed to authenticate.

Please follow the steps as displayed where possible, for your own chosen Token based API authentication service.

For those looking for a more detailed walk-through, checkout our Token example: Authentication examples: Token: Airtable

Pre-existing

You can also make use of authentications you have already created for Tray connectors.

For example you may already have used the Slack connector to e.g send messages, but there is a particular Slack API endpoint you want to work with, that is not accessed by any of our Slack connector operations.

Notes on using services

Extra / Optional parameters

You may come across extra or optional parameters when building a custom service.

Tray.io has split the main and optional extra parameter sections into two.

Once you have clicked through to the 'New service' page, you will see various sections that you will need to complete.

Scroll down to the final header called 'Authentication parameters'. This is where the optional or extra parameters are added as per your needs.

Authentication Issues (third party processing)

PLEASE NOTE: This issue is much more common with Embedded customers because its purpose is to deal with external user data.

Due to the very nature of our service, Tray.io is sometimes mistaken for a third party processor. While this is not the case, it is a common error.

It is especially common when authenticating with outside data processing services who for legal reasons, have stricter data protection policies.

Third party processing is often against their terms of use and API protocols. This surface level error can make the approval process for OAuth custom services (that want to work with Tray.io) a bit more difficult. Once clarified, all works as expected.

However until this happens, the authentications created within Tray.io in tandem with your custom service, may unexpectedly stop working..

Say you wanted to use a custom service under the following circumstances:

  • The custom service has been created within an umbrella application (such as Google Ad Manager or Facebook).
  • The umbrella application has a particularly high bar when it comes to processing end user data. Who can view email addresses, personal information, etc.
  • While you can use your custom service as normal, the status of your custom service has not yet been fully verified to work with Tray.io (by the umbrella application).

Until the custom service itself is fully verified by the umbrella application, and has the umbrella applications approval to work with Tray.io, any authentications created within Tray.io may become faulty or suddenly stop working.

This is because while the authentication may have passed Tray.io's standard, the custom service is usually only given a demo or test status level of approval. Usually this means the authentication/ refresh token/ etc will automatically expire after a short time frame.

Please contact your umbrella applications customer services in order to rectify the situation should this occur.

Authentication examples

OAuth2: Spotify

To demonstrate how to set up an OAuth2 based service, this demo will use the Spotify API Docs (otherwise known as the 'Authorization Guide') for the remainder of this example.

Token: Airtable

To demonstrate how to set up an OAuth2 based service, this demo will use the Airtable API (otherwise known as the 'Authorization Guide') for the remainder of this example.