# Token-based services 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. ### 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](#token-airtable) ### 1 - Add new service 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. ![http-auth-2-new-service](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-d27636da_custom-services-auth-issues.png) Make sure to fill in all the aspects of the **Details** panel as **each field is required**. ![http-auth-2-details](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-dc7dcaf3_custom-services-auth-issues-1%201.png) ### 2 - Select Token Select **Token-based** from the authentication section. ![http-auth-2-auth-type](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-9b8843c3_http-auth-2-auth-type.png) The panel below it will change accordingly (i.e. the Scopes section will be removed). You will only be left with **Authentication parameters**. ### 3 - Parameters: Title When it comes to using the **Authentication parameters** with a Token based authentication the most important field is the first parameter you add, the **Title** itself. **This is what your Bearer token will be referring to in order to access the API of your choice**. In order to clarify what title would be appropriate, you will need to head to your selected services' API documentation. You may also need to go to your service APIs' developers account, or your personal account section to get your user specific information. Sometimes service API documentation can be tricky to understand. If you get stuck, see our [Custom connectors: Reading API documentation](#reading-api-documentation) page section for more details. **The most important thing is to copy the api key format given EXACTLY**. Then reference it in the 'Title' section of your Tray.io 'Authentication parameters' section from earlier. Fill in the rest of the fields such as 'Type', and make sure that the checkbox 'Marked as required' is set to **Required**. ![http-auth-2-params](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-6659cb8f_http-auth-2-params.png) ### 4 - Parameters: Extra The 'Authentication parameters' section is where you include any other parameters/ properties you wish to add. > **Info:** **USER TIP**: This is the section where you add any and all extra or optional parameters, that are specific to your service. **Remember that certain services expect their parameters to be presented in a particular way** and that this must be adhered to in order to work properly. For example in the Query or Headers section of the call (for demo purposes this has been left blank). For more details see our [Custom connectors: Extra / Optional parameters](#extra--optional-parameters) page section for more details. ### 5 - Add your service 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, using the HTTP client connector as your trigger. 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). ![http-auth](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-19aee97c_OAuth2-%20Authorization%20code%20grant-7%201%20%281%29.png) ### 6 - Create authentication 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 newly created service. Depending on your service requirements you may also be asked for the token/ API key credentials on your 'Service permissions' model. ![http-auth-2-popups](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-2e7e3864_http-auth-2-popups.png) 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. ### 7 - Test setup The last stage requires a **test API call**. **The HTTP client connector will automatically have the operation set to 'POST'**. Depending on the scopes previously set, **select an API endpoint that is relevant** to your service setup. 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**. ![http-auth-2-debug](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-b79f84e8_http-auth-2-debug.png) It may be worth viewing the Output panel in more detail as the list of information gathered may be quite long, depending on the service ### Token: Airtable To demonstrate how to set up a token based service, this demo will use the [Airtable API](https://airtable.com/developers) for the remainder of this example. ### 1 - Select Token To authenticate with a Token based service, first go to the main Tray.io account dashboard. From the top, select 'Services' and click the 'New service' button in the top right. ![http-auth-2-new-service](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-d27636da_custom-services-auth-issues.png) Make sure to fill in all the required fields (**name** and **description**) of the 'Details' panel. ![http-auth-2-details](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-dc7dcaf3_custom-services-auth-issues-1%201.png) Select 'Token-based' from the authentication section. ![http-auth-2-auth-type](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-9b8843c3_http-auth-2-auth-type.png) The panel below it will change accordingly (i.e. the Scopes section will be removed). You will only be left with **Authentication parameters**. When it comes to using the **Authentication parameters** with a Token based authentication the most important field is the first parameter you add, the **Title** itself. **This is what your Bearer token will be referring to in order to access the API of your choice**. In order to clarify what title would be appropriate, we need to head to the REST API documentation itself. ### 2 - Airtable API docs For the purposes of this demo, the following explanation will use the [Airtable REST API](https://airtable.com/developers) for the remainder of this example. While the information here is unlikely to be in accordance with your own custom service, it is a useful reference when dealing with navigating the Tray.io Token panel and Token API documentation in general. > **Warning:** The API Docs you will need to refer to, should be at a URL similar to: > `https://airtable.com/appXXXXXXXXXXXXXX/api/docs#curl/introduction` > , (your own project/ Base ID hash after > `.com/app` > will vary). More information on how to get to this URL is explained further on. ### 3 - Head to the Developers site Go to the [Airtable API](https://airtable.com/api) site and sign into your account. This should lead you to on to the main [Airtable Developers site](https://airtable.com/developers). Select the 'WEB API' option to reach the main page (follow the steps displayed where possible for your own chosen Token based API authentication service). ![http-auth-2-developers](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-87bf43b8_http-auth-2-developers%201.png) ### 4 - Find your Base ID This will direct you to a list of your current projects. Choose the project in question you wish to authenticate with: ![http-auth-2-bases](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-e69c5e98_http-auth-2-bases.png) 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 REST 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, the 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.** ![http-auth-2-intro](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-f9f45176_http-auth-2-intro_1%201.png) ### 5 - Check your API limits The second section details the limitations found within the scope of your base's API. > **Warning:** **IMPORTANT!**: What is written here may effect your project so please read through this section carefully before proceeding. ![http-auth-2-api-limits](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-057c5a68_http-auth-2-api-limits%201.png) ### 6 - Get your API key The next section, the authentication section, outlines how to get your API key (aka your Token) via your [account page](https://airtable.com/account). It also mentions the need for an `api_key` reference should you choose to use query parameters instead of headers. **The most important thing is to copy the api key format given EXACTLY**. Then 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.** ![http-auth-2](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-fc2bb1a8_http-auth-2-auth.png) 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](https://support.airtable.com/hc/en-us/articles/219046777-How-do-I-get-my-API-key-). ![http-auth-2-account-page](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-c92305ad_http-auth-2-account-page.png) ### 7 - Set parameters 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. > **Info:** **USER TIP**: This is the section where you add any and all extra or optional parameters, that are specific to your service. 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 checkbox 'Marked as required' is set to **Required**: ![http-auth-2-params](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-6659cb8f_http-auth-2-params.png) ### 8 - Add your service Select the 'Add service' button in the top right hand corner. You will now see the newly created service under your Services tab. ![http-auth-2-add-service](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-cf39fc5d_http-auth-2-add-service.png) 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). ![http-auth](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-19aee97c_OAuth2-%20Authorization%20code%20grant-7%201%20%281%29.png) ### 9 - Create your Tray.io authentication 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). ![http-auth-2-popups](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-2e7e3864_http-auth-2-popups.png) Clicked 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. ### 10a - Set request type and bearer token For the sake of Simplicity, and to test your HTTP client connector is in fact working as expected, set the operation to 'GET'. ![http-auth-2-get-operation](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-bbdb61e7_http-auth-2-get-operation.png) 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/`. ![http-auth-2-base-url](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-781eba9b_http-auth-2-base-url.png) 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. ### 10b - Find your Base ID Go to and sign in. Click on the project (otherwise known as 'Base') you wish to use. Your Base ID can be found within the URL of your API docs themselves: `https://airtable.com/appPDWK5dasdw2/api/docs#curl/introduction`. The Base ID being the string after `https://airtable.com/`. Which means that in this example the base ID is: `appPDWK5dasdw2`. Note that this is also displayed within the introductory section of the Airtable API docs, as highlighted previously. ### 10c - Find your Table ID Go to `https://airtable.com/` and 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`. ### 11 - Setup complete Add these ID's the the end of the base URL as follows: `https://api.airtable.com/v0/appPDWK5dasdw2/tblefuahu4265d/` ![http-auth-2-url-endpoints](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-5646daab_http-auth-2-url-endpoints.png) 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` ![http-auth-2-query-params](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-3bddea1d_http-auth-2-query-params.png) ### 12 - Test the workflow 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. ![http-auth-2-debug](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/d4c81a92-b79f84e8_http-auth-2-debug.png) ## Note for Parameterization **Parameterization** allows you to provide the values for fields like Client Id, Client Secret and the API url at the time of creating authentications. It adds: 1. **reusability** as you can use different OAuth apps in different integrations by creating a single service 2. **security** as you don't have to expose the values in the services page and you will only feed them while creating the auth. Here's an example on how it can make your service reusable: ![parameterization shopify](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/3edujrcEnln1aLiGK0Clnh_parameterization%20shopify.png) Shopify has custom URL for domains, you can parameterize the url in the OAuth 2 settings by passing a placeholder as: `\{\{shopify_url\}\}` Now you can add the same placeholder value below in the 'Authentication parameters' section ![auth parameters parameterization](https://tray.ai/documentation/images/platform/connectivity/custom-services/token-based-services/2aMWCeveWlUqRyxLlFL5jK_auth%20parameters%20parameterization.png) \*\*NOTE: \*\*The unique property key has to match the placeholder value you passed in the settings.