Introduction

Overview

Copy

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

In such cases 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.

Note: *For embedded refer the note below.

Creating a service

Copy

Your custom services are available organization-wide. This means other users can also use this service for creating authentications. This does not mean they will be able to see and edit the custom service in their services section.

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

Note for Embedded

Copy

If you are an Embedded customer, the custom services must be created in the embedded workspace by the organization owner. The custom service will then be available for creating the authentication to other builders in yours organization as well. Finally, once you publish a solution, Your end users will also be able to authenticate with this custom service through the config wizard.

Reading API documentation

Copy

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.

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

Copy

There are two main methods of authenticating with the HTTP client connector: OAuth2, Token.

You can go through the pages in this section to find a basic setup guide for each method.

• OAuth2: Authorization code grant flow

• OAuth2: Client credentials grant flow

• Token

Every page contains a detailed walk-through using specific examples to demonstrate the full process.

Using pre-existing auths

Copy

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.

For such cases, You can also make use of authentications you have already created for Tray connectors.

Authentication Issues (third party processing)

Copy

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.

for the remainder of this example.

Notes on Importing

Copy

The usual import process currently does not support a project or a solution which has a custom service.

For Tray platform users, once you create a workflow/project that uses a Custom Service, please read these sections on Importing Project with a Custom Service, Importing Workflow with a Custom Service.

For Tray embedded users, once you create a solution that uses a custom service, please read the page on Importing solutions with a custom service.