# OAuth2 services This is the default and preferred way of authenticating services that use OAuth2 based authentication as it ensures high security. ## Overview This is the default and preferred way of authenticating services that use OAuth2 based authentication as it ensures high security. For this, you'll need to **create an OAuth app with the third party service**. You will then need: 1. **client ID and client secret** of the OAuth app 2. **authentication URL and access token URL** of your third party service Please follow the steps below: ### 1 - Add new service To authenticate with an OAuth2 based service, first go to the main Tray.io account dashboard. Select **Services** and click on the **New service** button in the top right. ![http-auth-1-new-service](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-098926ff_OAuth2-%20Authorization%20code%20grant-1%201.png) Make sure to fill in all the aspects of the **Details panel** as **each field is required**. ![http-auth-1-details](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-82124f55_OAuth2-%20Authorization%20code%20grant-2%201.png) ### 2 - Select OAuth2 **Select OAuth2** from the authentication section: ![http-auth-1-auth](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-8fc18779_oauth%20auth%20code%20auth.png) The panel below will change accordingly. With OAuth2 there are 4 field names required: • **Client ID** • **Client secret** • **Authentication URL** • **Access token URL** These will have been created along with the OAuth app for your selected service. You may also need to go to your service API developers account, or your personal account section to get your user specific information. Note the 'Advanced' section allows you to adjust to any particular requirements a service may have on how scopes and tokens are managed and formatted: ![oauth2-settings](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-4be6d232_oauth2-settings.png) ### 3 - Scopes The last authentication section to take into account will be the **OAuth2 scopes**. This section controls the level of access the Tray.io authentication has, in regards to your service account. **These will vary between API services**. A list of available scopes should be available within your API Scope documentation page. Select your scopes and make sure to choose appropriately depending on your project needs. To add a scope, set your cursor inside 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 input scope has now moved into the name field. To add a another, simply repeat the process. ![http-auth-1-scopes](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-ad11dc2c_OAuth2-%20Authorization%20code%20grant%204%201.png) ### 4 - Parameters The final **Authentication parameters** section asks if there are any parameters/ properties 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. ![http-auth-1-add-property](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-2dabfbe2_OAuth2-%20Authorization%20code%20grant-5%201.png) ### 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/oauth2-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. There will be a second page displaying the scope options if you set up any. ![http-auth-1-popups](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-0a50e13e_Group%2018.png) 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. ### 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**. ![oauth2-test-api-call](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-ff2b4017_oauth2-test-api-call.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: ![http-auth-1-output](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-39b26f0d_http-auth-1-output.png) ## Authentication Demo: Twitch To demonstrate how to set up an OAuth2 service with Client credentials grant flow, this demo will use the [Twitch API docs](https://dev.twitch.tv/docs/api/) for the remainder of this example. ### 1. Register an OAuth application Click on 'Register your application' on [Twitch developer console](https://dev.twitch.tv/console/apps). ![DEV CONSOLE TWITCH](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/4AzeAfyzGZ7zU6EomVzJRv_DEV%20CONSOLE%20TWITCH.png) ### 2. Fill in application details ![twitch app fill in details](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/UGhZjC3MY0UUf3stmxxTX_twitch%20app%20fill%20in%20details.png) If you are an embedded user, refer to the [note below](#redirect-url-note-for-embedded). ### ### 3. Copy client secret and client id ![twitch copy client id secret](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/2CLbMqB51RChUOlovQ69QQ_twitch%20copy%20client%20id%20secret.png) You will have to generate client secret once. Once done, copy both values and keep them safe as we will need them on Tray.io dashboard. #### ### 4. Add new 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-1-new-service](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/d4c81a92-098926ff_OAuth2-%20Authorization%20code%20grant-1%201.png) Make sure to fill in all the required fields (**name** and **description**) of the 'Details' panel. ![client creds details](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/11hbNF8eH1w7dFdDnDTdB0_client%20creds%20details.png) ### ### 5. Add Authentication parameters Skip the OAuth details and scroll down to 'Authentication parameters' section at the end of the page. Now, add parameterizations for client\_id, client\_secret. ![service auth parametrization](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/39Hl07PYf9ZCNPmxNPoc8C_service%20auth%20parametrization.png) Please note down the unique property key as this is what you will have to add in the authentication parameters above ### 6. Add OAuth 2 settings Now scroll up to **OAuth 2 settings** section and add the values for client\_id and secret as shown below. ![client creds settings](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/Hn1gdmQ2TxWzdfMzOAV0H_client%20creds%20settings.png) In this case, api\_url has been parameterized as well. In order to find the rest of the OAuth2 details, aka, the 'Authentication URL' and 'Access token URL'; head to the [Twitch API docs authentication](https://dev.twitch.tv/docs/authentication/getting-tokens-oauth/#client-credentials-grant-flow) section. All services have specific OAuth2 endpoints for authentication and access tokens. These endpoints invariably end in variations of: '/authorization' and '/token'. **Authentication URL**: `https://id.twitch.tv/oauth2/authorize` **Access token URL**: `https://id.twitch.tv/oauth2/token` ### 7. Save changes and use the service Now click on save changes and your service is now ready to use. You can use an HTTP client in the workflow builder. While adding the authentication search for your service and create the auth. ![add auth http twitch](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/4XIRzaWfYdNYSolkBEjRgm_add%20auth%20http%20twitch.png) Now, you can set up the Authorization header and any other required by the service. Twitch requires Client-Id to be sent as one of the headers. ![http headers twitch](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/52jkn0LdRWGUfMxhpDAl9P_http%20headers%20twitch.png) Add the API endpoint and run the workflow. ## Redirect URL note for embedded If you need a white-labelled solution, you can add another redirect URL `.integration-authentication.com/oauth2/token` Example: `acme.integration-authentication.com/oauth2/token` ![embedded twitch redirect](https://tray.ai/documentation/images/platform/connectivity/custom-services/oauth2-services/3Tm7kCXyVTFaXoOVwASwK2_embedded%20twitch%20redirect.png) > **Info:** Your first redirect URL should still be `auth.tray.io/oauth2/token` followed by `acme.integration-authentication.com/oauth2/token` in second place. If the service doesn't support more than one redirect URL, check out two workarounds [here](https://tray.io/documentation/tray-uac/embedded-integrations/css-and-whitelabelling/custom-oauth-apps/#single-redirect-url-issue). The above URL will replace the redirect URI query parameter in the config wizard/auth-only domain when your end users configure their solution instances. > **Info:** If you wish to have your self-hosted redirect URL, please contact support as it would require setup from our side. ## 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/oauth2-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/oauth2-services/2aMWCeveWlUqRyxLlFL5jK_auth%20parameters%20parameterization.png) **NOTE:** The unique property key has to match the placeholder value you passed in the settings.