HTTP Client

OAuth2

To authenticate with an OAuth2 based service, first go to the main Tray.io account dashboard. On the left hand side, select 'Services' and click on the 'Add new service' button in the top right.

To demonstrate how to set up an OAuth based service, this demo will use the Spotify API Docs (otherwise known as the 'Authorization Guide') for the remainder of this example. Please follow the steps as displayed where possible, for your own chosen OAuth based API authentication service.

Make sure to fill in all the aspects of the 'Details' panel as each field is required.

Select 'OAuth2' from the authentication section:

The panel below will change accordingly. With OAuth2 there are several field names required: 'Client ID', 'Client secret', 'Authentication URL' and 'Access token URL'. Fill these in as in accordance with your selected OAuth2 based API service. For the purposes of this demo, the following explanation will use Spotify for the walk through.

Head to your dashboard within your Spotify for Developers account.

You should see a list of applications available. If you don't have any, create one.

Once created you will immediately be directed to the applications settings. Here you will find the relevant 'Client ID' and 'Client secret' that you need for your Tray.io OAuth2 authentication setup. Copy and paste them appropriately.

Note that each new service authentication needs to known what is the Redirect URL is (the URL made available by the Tray.io platform). In this case it is: https://auth.tray.io/oauth2/token and can be found in the same section of the Tray.io OAuth2 service page:

This will need to be entered in the settings of your custom app, so go back to the Spotify application settings page (where the 'Client ID' and 'Client secret' were found) and select the 'Edit Settings' button.

'Add' the redirect URL into the redirect URL field option.

In order to find the rest of the OAuth2 details, aka, the 'Authentication URL' and 'Access token URL'; head to the Spotify API Docs themselves.

All services have specific OAuth endpoints for authentication and access tokens. These endpoints invariably end in variations of: '/authorization' and '/token'. A quick serach for the following terms: spotify.com/authorize and spotify.com/api/token should result in these two URLs:

Authentication URL: https://accounts.spotify.com/authorize

Access token URL: https://accounts.spotify.com/api/token

Once more copy both into your Tray.io OAuth2 authentication setup.

The last authentication section to take into account will be the 'OAuth scopes'. This section controls the level of access the Tray.io authentication has in regards to your Spotify account. These will vary depending on your API (Spotify is capable of several).

A list of available scopes should be found within your API Scope docs page. For more details on Spotifys please view this link. you can add and delete as you see fit.

Select your scope and make sure to choose appropriately depending on your project needs. For this example the user-library-read scope has been selected as it allows for read access to a user's library. For more information please see the 'User Library Read' section within the scopes list.

To add this, set your cursor in the input field and type in the name of the scope. Press enter. An expended panel will display asking for your scope description. As you will see, the previously inputted scope has now moved into the name field.

To add a another, simply repeat the process.

The final 'Authentication prameters' section asks if there are any parameters/ properties to add. Note that certain services that expect particular parameters present in a particular way in the Query or Headers section of the call (for demo purposes this has been left blank).

Select the 'Add service' button in the top right hand corner. You will now see the newly created Spotify service under your Services tab.

Select 'Workflows' from the left hand menu, to get back to the main Tray.io account page.

Choose or create a workflow and once within the workflow builder itself, search and drag the HTTP client connector from the connectors panel (on the left hand side) onto the workflow.

With the new HTTP client connector step highlighted, in the properties panel on the right, click on 'Add new Authentication' (located under the 'Authenticate' tab).

This will result in a Tray.io authentication pop-up window. The first page will ask you to name your authentication, and state which type of authentication you wish to create ('Personal' or 'Organisational').

As you can see, there is also a third option which requires the user to select which service they wish to authenticate with. In this use case, we will be selecting the 'Spotify Docs Demo' service, which was just recently created.

The second page of the popups will display the scope options set earlier.

Once all the relevant scopes have been selected, click on the 'Create authentication' button. Go back to your settings authentication field (within the workflow builder properties panel), and select the recently added authentication from the dropdown options now available.

The last stage of authentication setup requires a test API call.

Finding the exact API call you want to make

Depending on the scopes previously set, select an API endpoint that is relevant. This will require some investigation of the API docs themselves. In this demo we are using the following request 'Get Current User's Saved Albums', as this will work in well in conjunction with the user-library-read scope set earlier.

The HTTP client connector will automatically have the operation set to 'POST'. Change this to 'GET'.

You will need to provide the Spotify URL (including relevant 'Endpoint') and 'Bearer token' in order to make this operation work correctly.

To confirm what these are, return to the Spotify service's API Reference Library. As you can see from the below images, there are several points within the guide that highlight the need and format of both the base URL (https://api.spotify.com/v1/me) and the need for a 'Bearer' token:

Fill in the details for the Spotify API call and make sure to add the appropriate 'Header' / 'Key' - value pairs for the Bearer token setup.

For Spotify, completion of setup would look as follows (note that the access_token key is generated from the earlier authorisation parameters step, and uses Tray.io's interpolation method):

Run the workflow. In your Debug panel you will see a green workflow run indicating that the token was accepted and your authentication setup is complete, not to mention a list of albums:

It will be worth viewing the output panel in more detail as the list of information gathered will be quite long, depending on the users Spotify usage:

Token based

To authenticate with a Token based service, first go to the main Tray.io account dashboard. On the left hand side, select 'Services' and click on the 'Add new service' button in the top right.

To demonstrate how to set up a Token based service, this demo will use the Airtable REST API for the remainder of this example.

Make sure to fill in all the aspects of the 'Details' panel as each field is required.

Select 'Token-based' from the authentication section.

The panel below it will change accordingly. The most important section being the 'Title'. This is what your Bearer token will be referring to in order to access the Airtable REST API.

In order to clarify what title would be appropriate, we need to head to the Airtable REST API documentation itself.

Go to the Airtable API site & sign in.

This should lead you to on to the main Airtable Developers site.

Select the 'REST API' option to reach the main page (follow the steps displayed where possible for your own chosen Token based API authentication service).

This will direct you to a list of your current projects and what Airtable refers to as your 'Bases'. Choose the project in question you wish to authenticate with:

Airtable states that: "after you’ve created and configured the schema of an Airtable base from the graphical interface, your Airtable base will provide its own API to create, read, update, and destroy records." This means that depending on the project you select from your available bases, your API docs will be 'unique' to and your needs.

The URL you will be redirected to, should look similar to: https://airtable.com/appXXXXXXXXXXXXXX/api/docs#curl/introduction. This is where your REAT API documents for this particular base/ project will lie.

In the introductory section, you will also be presented with your project's/ Base's unique ID. This is also held within the actual URL, as exampled above, yhe Base ID being the string after: https://airtable.com/. It should start with app.

Take note of this Base ID, and where it is located. It will be needed later on during the authentication process.

The second section details the limitations found within the scope of your base's API.

The next section, the authentication section, outlines how to get your API key (aka your Token) via your account page.

It also mentions the need for an api_key reference should you choose to use query parameters instead of headers, but the key thing here is to copy the api key format given, and reference it in the 'Title' section of your Tray.io 'Authentication parameters' section from earlier.

Take note of this Base ID, and where it is located. It will be needed later on during the authentication process.

You will need the API key from your account page, in order to authenticate with Tray.io.

This is referenced as 'the Airtable API Key within Airtable', and as 'the Token' within Tray.io.

Note that it can be regenerated via your account page if need be. For more details on how to get your Airtable API key, follow the link here.

With this information in hand, head back to your Tray.io services page, and make sure to add any and all properties to the 'Authentication parameters' section, as per your API service documentation specifications. In this use case it will require the following:

In the case of Airtable, the 'Title' should be set to 'api_key'.

As you can see, this will automatically generate a unique property key: api_key which is the required key type.

Set the 'Type' to 'Password', and make sure that the tickbox is set to Required; the end result should be as follows:

Select the 'Add service' button in the top right hand corner. You will now see the newly created service under your Services tab.

Select 'Workflows' from the left hand menu to get back to the main Tray.io account page. Choose or create a workflow and once within the workflow builder itself, search and drag the GraphQL connector from the connectors panel (on the left hand side) onto the workflow.

With the new Http client connector step highlighted, in the properties panel on the right, click on the Authenticate tab and 'Add new authentication' (located under the 'Authentication' field).

This will result in a Tray.io authentication pop-up window. The first page will ask you to name your authentication, and state which type of authentication you wish to create ('Personal' or 'Organisational').

As you can see, there is also a third option which requires the user to select which service they wish to authenticate with. In this use case, we will be selecting the 'Airtable Docs Demo' service, which was just recently created.

The second page of the popups will ask for an API Key. Add the Airtable API Key to this field (this was acquired from your account overview page earlier).

Once you have clicked on the 'Create authentication' button, you will see the authentication within the authenticate tab, with the corresponding label (i.e. 'Personal' or 'Organisational').

For the sake of Simplicity, and to test your Http client connector is in fact working as expected, set the operation to 'GET'.

Switch to the Input data tab. You will need to provide the Airtable URL (including relevant 'Endpoint'), plus the necessary 'Bearer token' in order to make this operation work correctly.

The base URL for Airtable is found within the API Docs, and can be seen under any example request: https://api.airtable.com/v0/.

The endpoints you will need to reference include the Base ID and your Table ID. These can be found in the URL's of your project.

To find your Table ID

Go to https://airtable.com/ & sign in. Click on the table you wish to use. The Table ID will be found within the URL of your browser, which should look similar to: https://airtable.com/tblefuahu4265d/viw0T6SXtRlRJUQLR?blocks=hide. The Table ID being the string after https://airtable.com/, but before /viw0T6SXtRlRJUQLR?blocks=hide.

So in this example the Table ID would be: tblefuahu4265d.

Add these ID's the the end of the base URL as follows: https://api.airtable.com/v0/appPDWK5dasdw2/tblefuahu4265d/

In order to make a successful API call and make sure to add the appropriate 'Header'/ 'Key' - value pairs for the Bearer token setup.

For Airtable, completion of setup would look as follows (note that the value: api_key is generated from the earlier authorisation parameters step, and uses Tray.io's interpolation method):

Query Parameter: Key: Authorization Value: Bearer {$.auth.api_key}

Run the workflow. In your Debug panel you will see a green workflow run indicating that the token was accepted and your authentication setup is complete.

Pre-existing

From the dropdown options available under the Services heading, select a pre-exsisting Tray.io service connector to connect the Http client connector with; (all connectors currently available on the Service Connectors page will be listed as an available option):

The second authentication page will be entirely dependent on what the service selected now requires. You may need to provide scopes, permission settings, client secrets, etc. Please see the relevant Tray.io service page documentation for further details on completion of setup.

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.

OAuth2 advance features

There are several advanced features available within the OAuth2 Advanced properties section, designed especially for those who wish to take use alternative settings depending on their needs. Below the following features are explained:

• Authorisation type - Set the authentication type and HTTP headers behind the scenes. May be used in conjunction with setting up your own custom refresh logic as well. More details on how to use these features of the Authentication type field, can be found below.
• Follow redirect - For if you want to move a webpage to a new location (redirects are not followed by default).
• Reject unauthorised - By default this is pre-ticked for 'true', everything is HTTPs. Users are able to disable the secure functionality if need be here.
• TLS - Users can adjust their own HTTPs protocol. By default the connector states its coming from Tray.io but this enables users to change the security information if need be and set the TLS setting in the HTTPs request.
• Parse response - Automatically generated as a string, this can be changed to make the response JSON or XML etc.
• Force file response - Instead of returning the response as a json object, this feature returns it as a file which can be downloaded.
• Force file resonse name - The name of the file if the response is forced as a file object.
• Status codes - Depending on the version number of the workflow in question, the connector will terminate depending on the status code. This feature allows users to specify the status codes that the HTTP client should expect as per their requirements. See Dealing with statuses returned by your calls for more details below.

Authorisation type cont.

For more information on how to use both aspects of the 'Authorisation type' advanced properties feature, please see below for more details.

Authorisation type

When using the OAuth2 type authentication method, users have two options. They can either follow the method outlined above where the Bearer token is displayed within the main properties panel, or forgo the use of the Bearer token within the main properties panel and set the HTTPs headers behind the scenes instead.

Unless the user considers themselves a power user of Tray.io, it is recommended that the method outlined within the OAuth2 section above be followed. Because the nature of this method is hidden, users may find it confusing if they are unfamiliar with Tray.io advanced features in general. Users who follow in their stead may also find the workflow difficult to understand, as the bearer token is not obvious at first glance within the properties panel.

Using this method still means that the authentication type will be declared through the use of HTTP headers, only that the Bearer token itself will be 'absent'.

To utilise this method, head to the bottom of the properties panel input tab, and click on the 'Show advanced properties' button. Scroll until the 'Authentication type' field becomes visible.

Select OAuth2 and change the input type of your 'Access token' to jsonpath.

The Bearer section of the token path is already set for you here, and therefore 'absent'. Since it is set behind the scenes, you need only add the latter half of the token path: $.auth.access_token.

When run, you should see the 200 status code with your Debug panel, as confirmation of a successful run.

Clicking on the 'Hide advanced properties' button will remove this field from the users view.

Dealing with statuses returned by your calls

Variables

All variables passed as query parameters are HTML-escaped automatically.

Pagination

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.

Headers

Please note that users must include the authentication information in the headers of the HTTP client connector request, except when using the OAuth2 method (as this can be set behind the scenes). See the Authentication type section above for more details.

Binary files

It is possible to use the HTTP client connector to send files across in a binary format using the 'Body type' -> 'Binary' option.

When a user sends a file using the 'Body type': 'binary' property, Tray.io will stream the data of that object to your endpoint.

The end result will be a string output, found within your output panel under the JSON key name: "body".

For the sake of clarity, this example will use two small Tray.io workflows to show the transportation of the data more clearly.

Using the Form trigger, set the operation to 'Form request'. Using the following properties panel field information, the first workflow will trigger once a file is uploaded online.

Note that you can get the URL of your form trigger via the settings icon within your workflow builder.

Once at the URL in question, upload the file you wish to send in binary format.

The file itself can be in any format, as the point of this exercise is to prove that during the "send" process between workflows, the file will be sent in binary format (not that it was as such to begin with).

Add a HTTP client connector as your next step. Set the operation to 'POST'.

Create a secondary workflow, this time using a Webhook as your trigger. Copy the public URL reference for this secondary workflow, and go back to the original workflow.

In the first workflow's HTTP step, place the new URL within the 'URL' field. Set your 'Body type' to 'binary' and create a jsonpath from your trigger within the binary field itself: $.steps.trigger.result.Test[0]:

Within the second workflow, once the form is uploaded again, the second webhook trigger will be notified. This is proven by the green log and output of the debug panel.

The file itself, having travelled in binary format, can be found under the "body" key in the output panel.

Regardless of the original format, the data type will now be string. All the data from the original file will now be available to view in a single line of output, as displayed below:

Multipart file uploads

Note that files can also be uploaded in multiple parts when using the form-data option.

This is found within the 'Body' type field.

1 - Setup trigger & HTTP client conntector

Once you have clicked 'Create new workflow' from your main Tray.io dashboard named it, select the Manual trigger from the trigger options available:

After you have been redirected to the Tray.io workflow dashboard, from the connectors panel on the left, add a HTTP client connector to your second step. Set the operation to 'GET'.

Using the authentication method described above utilising the Airtable API, fill in your properties panel appropriately. Bear in mind that in this example, a sample table has been provided and you will need to create your own dummy data in order to continue this tutorial.

Feel free to re-name your steps as you go along to make things clearer for yourself and other users.

2 - Loop through the data

Next, search for the Loop collection connector within your connector panel, and drag it into your workflow as your next step. Set your operation to 'Loop list'.

The Loop Collection connector allows you to iterate through a list of results. In this example, we will use it to iterate through the data found within the previous HTTP Airtable connector step.

In order to specify the list you want to loop through, start by using the 'List' mapping icon (found next to the list input field, within the properties panel) to generate the connector-snake.

While hovering over the 'Get client data' step (with the tail end of the connector-snake), select records from the list of output properties displayed. This will auto-populate a jsonpath within your 'List' input field, and update the type selector to jsonpath.

You may find that the loop step does not automatically display every path option for you (i.e. the records option may not be displaying in the connector-snake list). If this is the case, for more clarification on the pathways you have available to you, open the Debug panel to view your step's Input and Output.

Once you have confirmed your pathway, use the 'Use output' button to generate the full list of available options.

The newer options will now be displayed alongside the previous outputs under the 'Output data' tab. The jsonpath you need should now be available when you right click the output option here, or when you use the connector-snake as usual.

By doing this, the workflow will now iterate through each record found within the Airtable table from the previous step, and gather all the information available for each record.

3 - Confirm collection

Go back to the connector search panel and place a Boolean condition connector inside of the Loop collection step itself. Set the operation to 'Boolean condition'. As you can see, the condition values must be set in order to continue.

As there are two types of categories within the Airtable dummy data set, the point of this branch is to make sure that only the records attributed to the brand identity label are processed. This is therefore the condition that needs to be set.

Use the connector-snake once more to fill in the first value of the conditions. Make sure to select category from the options displayed. Your jsonpath should look like this (depending on your own dummy data settings): $.steps.loop-1.value.fields.Category.

Set the 'Comparison type' to 'Equal to', and the second value condition itself as hardcoded string; in this case 'Brand Identity'.

Now if the record type has the category of brand ID, it will result in an action.

4 - Create contact card

On the false branch of the Boolean condition, add a Terminate connector step. When the record type is not equal to brand ID, there will be no actions taken.

Finally drag a Trello connector inside of the condition step, making sure to place it on the true path. Set the operation to 'Create new card'.

Select the board and list you wish to update. While the other fields are not required, 'Name' and 'Due date' would be useful.

If you are using the 'Due date' field, note that if you are not hard coding it, aka using the calendar option, that your jsonpath is accurate and does nto include any white space.

The end result should look similar to this:

The best way to confirm a positive workflow run is always to verify this in the Debug panel:

When reviewing your Trello board, your new cards along with all the information that was collected from the Trello step itselfshould now be on display within the cards themselves: