Introduction
Custom services overviewCopy
Creating a generic service authentication is the most straightforward way to use a service that is not included in our list of connectors. Please see our Authenticating Connectors page for details on creating one.
You cannot create a generic service auth for complex and Oauth-based authentications. In such cases, we recommend creating a new service.
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.
Once you have built a custom service, you can then use the Http Client to make all the calls you need to the service.
When you are creating a custom service in Tray, you are basically creating an authentication mechanism for a particular 3rd party service.
A key point to be aware of is that this allows consumers of your service - whether it is you as a Tray workflow builder or it is external End Users of your Embedded integrations - to authenticate themselves.
This can be done using either:
OAuth protocols - here the user can authenticate by sharing a logged-in OAuth session. In the Tray build UI or the Embedded Config Wizard the auth dialog will either pick up the session automatically or prompt the user to login
Token-based auth - here the user can authenticate by entering e.g. an API key or access token
When creating OAuth-based services, it is important to note that keys such as ClientID and Client Secret are set only once by you to configure the service (i.e. these are not auth credentials to be provided by consumers of the service).
Note that, while it uses its own mechanism for creating services / auth apps, this information applies also to the Connector Development Kit (CDK)
Creating a serviceCopy
Custom services can be created in any workspace:
Any user whose role is contributor or above can create, edit or delete the custom services in that workspace.
They can also use custom services to create authentications in that workspace.
If a service is created in your Organization workspace then it is 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.
Legacy Custom ServicesCopy
Using the 'Legacy' tab in your Personal workspace it is possible to view Custom Services that were created in the legacy system (whereby you could only create services in personal workspaces and they were available org-wide).
It is recommended to delete all services in Personal workspaces and recreate them elsewhere, as they will be deprecated at some point in the near future.
Note on Importing and ExportingCopy
If you are importing a workflow which uses a custom service then please make sure that the service is shared with the workspace where the workflow is being imported to.
Currently there are two ways to share the service with the workspace:
Create the service in the Organization workspace
OR
Use the service in a custom connector then share that connector with the workspace where the workflow is being imported to.
Otherwise the import will fail.
The exception is if the service is being only used in the Graph QL or HTTP client connectors.
In this case the user will get the option to choose the service from the list of services available in the workspace where the workflow is being imported to.
Note for EmbeddedCopy
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 your 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 documentationCopy
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 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 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 methodsCopy
There are two main methods of authenticating with the HTTP client connector: OAuth2, Token.
IMPORTANT!: While it is possible to also authenticate with OAuth2 Password grant flow and OAuth1, we do not recommend these unless absolutely necessary due to the security risks they pose.
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 authsCopy
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
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 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) a bit more difficult. Once clarified, all works as expected.
However until this happens, the authentications created within Tray 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 (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, any authentications created within Tray may become faulty or suddenly stop working.
This is because while the authentication may have passed Tray'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.