Whitelabelling with Custom OAuth apps

When building integrations with Tray's API, you will need to authenticate your End Users with the service connectors involved.

This can be done by:

By default the auth-only dialog URL will begin with:

  • https://embedded.tray.io (US region)
  • https://embedded.eu1.tray.io (EU region)

With our whitelabelling option you can use a wildcarded domain:

  • *.integration-authentication.com (US region)
  • *.eu1.integration-authentication.com (EU region)

Creating Custom OAuth apps

In order to create a Custom OAuth app you will have to:

  1. Create it in the 3rd-party UI (Salesforce, Mailchimp, Zendesk etc.)
  2. Log in to the Tray builder at https://app.tray.io/ to set up your app as a 'Service Environment' for the service connector in question

A detailed breakdown of the steps involved in creating a Custom OAuth app is:

1 - Create an OAuth app in the 3rd party UI

Create the OAuth app (in e.g. Salesforce, Mailchimp, Zendesk etc.):

  • Give it a name
  • Include your company logo
  • Set the main redirect / callback url to the default - https://auth.tray.io/oauth2/token (US) or https://auth.eu1.tray.io/oauth2/token (EU)
  • Set a second redirect / callback url as e.g. https://acme.integration-authentication.com/oauth2/token (US) https://acme.eu1.integration-authentication.com/oauth2/token (EU) (if the service supports entering multiple urls)
  • Retrieve Client ID, Client Secret etc. to use in step 2

Some services do not allow adding two redirect urls.

Please see our Embedded documentation on whitelabelling for info on how to deal with this.

2 - Create an OAuth app in Tray

You will then need to create a Tray workflow and add a connector step for the service in question.

Then create a new authentication for it and, in the auth dialog, click 'Use own OAuth app' and enter your app details (typically you will have to enter the Client ID and Client Secret retrieved from step 1 here):



The scopes that you select when creating this auth will be the scopes that are available for your End Users to choose from.

3 - Get Service Environment

Any custom auth apps you create will then have a serviceId which can be retrieved using the Get service environments endpoint

	"elements": [
			"id": "474a0059-xxxx-xxxx-xxxx-06f090088d70",
			"title": "Production",
			"authenticationType": "oauth2",
			"userDataSchema": {...},
			"credentialsSchema": {...},
			"scopes": [...]
			"id": "634dadf7-xxxx-xxxx-xxxx-446233ac09e9",
			"title": "Acme mailchimp custom OAuth app",
			"authenticationType": "oauth2",
			"userDataSchema": {...},
			"credentialsSchema": {...},
			"scopes": [...]

Please also see individual service connector pages for specific notes and guidance on creating auth apps for those services.