Open Navigation

Http Client (Universal Connector)

make calls to any REST, SOAP or GraphQL API


The Tray HTTP Client provides a way to manually make API requests to a specified URL. You can use the HTTP client to make calls to any REST-based, SOAP-based or GraphQL-based API.

There are two main uses for this connector:

  1. To make a call to an endpoint which is not yet used by any of the operations available in the Tray connector for e.g. Salesforce, Hubspot, Trello, Airtable, etc.

  2. If no Tray connector actually exists for a service, it can also be used to effectively build your own connector by creating a new authentication and passing a token as a parameter.

    In this case it is likely that you will wish to use the HTTP Client in conjunction with the Webhook Trigger. This will enable you to create workflows which are also triggered by an event in the service for which there is as yet no Tray pre-built trigger or connector.

Using the HTTP Client

As a simple example, you might have a table in Airtable (or another service which has sheet/database-like functionality) and want to use the HTTP client to pull in data from it, perform update operations etc. (note that we do actually have a Airtable Connector so you should not actually need to use the HTTP client, but Airtable serves as a good simple example of the Http client's functionality).

The following basic steps can take you through what is required to get going, and introduce you to what is required when using the HTTP client for any service:

First of all decide what source material you are wanting to query. In this case we are wanting to interact with a particular table of prospective customers in Airtable:


To find out the endpoint we need to query for this table, we need to research Airtable's API docs.

In this case we just want to make a simple 'list records' request to pull the customers into our Tray workflow. We are provided with an example request which shows the url for the endpoint we need


We can then use an HTTP client step to specify a GET operation at the endpoint for that table (note that you will also need to create an authentication for your service. Please see the authentications section below):


Once we run our workflow we can inspect the output of the debug panel to see that the customer details have been successfully pulled from the table:


Note that, for step 3 above, you will also need to create an authentication in order to access the service.

Intro to Authentication

The exact requirements for authenticating API calls will vary from service to service. Via the service API documentation, you will need to research exactly what format is expected, as well as how individual endpoints are used and what query parameters are expected.

Once you have ascertained what type of auth (basic/token or OAuth) you can follow the appropriate instructions below.

Basic (non-OAuth) Authentication

If your service uses basic token-based authentication, you can create and use an authentication by:



The created authentication can then be used in your API call by including the path $.auth.token (token will change depending on how you named it in step 1). Depending on the exact requirements of the service you are connecting to, this could be as a token in the query parameters:


Or it could be that it needs to be passed as a Bearer in the header:


Note: different APIs need to be authenticated in different ways, for example via:

  • Query parameters (as in the first example above)

  • Headers (as in the second example above)

  • Basic authentication (username & password)

  • Access tokens (OAuth refresh)

To view settings related to the last two, click on "Show advanced settings" for the properties and you'll see the following:


Using existing OAuth authentications

If you have a service which uses OAuth that you have already authenticated to using its pre-built connector, you can re-use this OAuth in an http-client.

To test this out, you can try a quick setup which will post a message to a particular Slack channel:

  1. Create a new Workflow with a Manual Trigger

  2. Add an Http Client as the next step

  3. Choose your previously configured Slack Auth as the Authentication, set the API Operation to POST and enter as the endpoint URL:


  4. Now you need to specify some query parameters:


    As you can see you need to enter the Slack Channel ID (found in the url when you have selected a particular channel e.g. and the text for your message.

    As another parameter, you have to add the token which can use an auto-completed jsonpath to pull the access token from the auth details:

    Details on the accepted format of parameters for this Slack API are at

    Once you have finished, you can click 'Run Workflow Now' and the test message should be sent and you can check the debug info:


Adding a new OAuth service

It is also possible to build an OAuth2 authentication 'from scratch' by going to and clicking on Add new service:


When creating a new service you are presented with the following screen which asks you to enter several details, including the following OAuth2 settings:


For each service you wish to configure you will have to:

  • create a custom app in the service UI so as to generate a Client ID and Client Secret.
  • obtain the generic endpoints the service makes available for Authentication URL and Access Token URL (these invariably end in /authorization and /token)
  • add the redirect url to the custom app settings in the service UI
  • investigate the required access 'scopes' (i.e. permissions) and endpoint involved in making the desired call to the service API so you can build your individual operations

Example service - Spotify

To give you an example of how this is done, we will take you through investigating and setting up a simple call using the Spotify API.

The ultimate aim here will be to produce an API call which carries out the simple task of listing a Spotify User's saved albums.

Part 1 - configuring a custom app in the service

The first stage of the process is to create a new Spotify app:


You are then presented with your Client ID and Client Secret:


These can then be added to the service fields above.

All services have specific OAuth endpoints for authentication and access tokens. These endpoints invariably end in /authorization and /token

To get these exact fields for a particular service, you can google for e.g. 'spotify authorization oauth' or 'hubspot authorization oauth'.

With Spotify this leads us to a page (if you were using a different service such as Hubspot, you would come to a similar page such as

In the spotify authorization page you will find the following example authorization call:


This gives us the url which can be used to populate the Authentication URL.

On the same Spotify page we can search for '/token' and find the token url:


This gives us the url which can be used to populate the Access Token URL.

Each service will need to be told what is the Redirect URL made available by the Tray platform.

This is and is found in the new service page:


This will need to be entered in the settings of your custom app:


Note: If possible, as above it is recommended that you add two redirect urls - one with a / and one without, to account for the fact that some services only work with a / and some won't.

To control the level of access you want your Tray authentication to have you can set the 'scopes'.

You will need to find a page which lists the OAuth scopes for your service, such as


In this example we are just wanting to list albums a user has saved, so we can use the user-library-read scope:


Part 2 - Completing and using the service setup in

Once all 5 of the above steps are taken care of, you will have all the necessary details filled in for the service:


Once the service is added you can return to your workflow and select it from the dropdown list:


And you can confirm the scopes being requested:


Constructing an API call

Finding the exact call you want to make will require some investigation of the API for the service. In this case we have found the following page which gives us the API to list a user's saved albums:


So we can now construct the GET request in the builder as such:


Note that we have used interpolated mode to add Bearer {$.auth.access_token} as an Authorization key in the 'Headers' section.

This is because, back on, we find an example call to the spotify API which uses an OAuth token:


Testing the call

If we run the workflow we can then check the debug output to make sure it has been successful.

Adding extra parameters

Note that when setting up your service it is possible to add extra parameters, to allow for certain services that expect particular parameters present in a particular way in the Query or Headers section of the call:


General notes on HTTP client usage

The HTTP Client intelligently handles data to make things as simple, reliable and consistent as possible. Here's some of the measures we take:

  • All variables passed as query parameters are HTML-escaped automatically
  • The Content-Type header is automatically set depending on the body provided, with application / x-www-form-urlencoded being set if none is selected. Additionally, the Content-Type of the request can be set / overwritten by explicitly specifying it in the header.
  • The Accept header is fixed to application/json, with a few exceptions. If the body is set to none, or the automatically detected Content-Type (dependent on the body) is either text / plain or application / x-www-form-urlencoded, then Accept is not set. Additionally, the Accept value of the request can be set / overwritten by explicitly specifying it in the header.

The available operations are GET, POST, PUT, PATCH, DELETE and HEAD

Testing your setup

The best way to check that everything is running properly is to use a manual trigger to call your API and inspect the logs to see what messages are being passed back and forth. We also recommend using a service like Postman for exploring APIs.


Tray has a page limit of 1 MB. So calls to APIs may return errors if the body of the returned content is too large.

To prevent this happening, you should implement a pagination method which is appropriate to the type of API calls you are making.

Dealing with Statuses returned by your calls

Each time an operation makes a call, as long as a connection is made and a status is returned Tray will not consider that an error has occurred - i.e. a status of '403 - Forbidden' or '504 - Gateway Timeout' will not result in a Tray error which would be managed using our Error Handling methods.

If 4xx and 5xx statuses are likely to be encountered, the Tray boolean and branch connectors can be used to set up a path for dealing with these cases.

Was this article helpful?