Tray Embedded / Core Topics / Authentications / Importing authentications

Importing authentications

The process of importing authentications can help you create a seamless branded experience and to save End Users who are already registered with your product having to register and authenticate again. It can be used to import authentications for your own product, or from other major token-based services supported by Tray (Zendesk, Marketo,etc.)

The steps involved

  1. In the Tray app UI, when you are creating a solution you should make sure that the authentication option is hidden from the End User when they are configuring their solution instance in your external UI. At this point you should also allocate an External ID to the authentication, as this is required when finally creating a solution instance.
  2. In your external app, when registering a new user, creating their access token etc. (as per the Main Process) you should use the createUserAuthentication mutation to create an authentication. When using this API, in order to specify which service you are creating an authentication for, and to supply the correct auth details you will need to specify the serviceId, the serviceEnvironmentId and the auth data (api key, domain, etc.) will need to be passed in the data field. These details can be obtained from the Profile section in the Tray UI.
  3. The createUserAuthentication mutation will return an authenticationId which can then be passed (along with External ID from step 1) when you are using the createSolutionInstance mutation which is required when you are activating a solution for an End User.
  4. Remember that once a Solution Instance has been created, the final step in activating it for an End User is to use the updateSolutionInstance mutation to set the status to 'enabled'.

Important note on OAuth services

If you are the actual owner of the service for which you are importing authentications, and it is OAuth-based authentication, it should be fairly simple for us to facilitate importing auths because you have complete control over the authentication service. Please contact us at to discuss any particular requirements. Note also that, if your service is one that allows configuring multiple custom environments for your End Users to log into, we can cater for this, as explained in [Custom Auths](
PLEASE NOTE: That importing auths for **third-party OAuth services (such as Slack and Salesforce)** which you are not the owner of is problematic and so is **not generally supported**. OAuth is not designed to be used in this manner (particularly with OAuth 2.0 and its security specs which restrict the sharing of tokens between services as detailed [here]( So there will likely be issues with how the authentication works and whether importing external auths can actually be done.

Therefore for third-party OAuth services it is most likely that you will have to ask your End Users to authenticate using the config dialog presented in the Config Wizard.

1 - Set the hidden authentication field in the UI

First, when creating/edting your Solution, set the Authentication as hidden in the UI, by dragging it to the Not visible to the users section as per the below screenshot:

From this you can pick up the External ID which must be passed when you are creating the Solution Instance in step 3.

2 - Create the authentication

Before you create the authentication you need to go the Profile section of your dashboard and use the Partner authentications import generator to obtain the serviceId, serviceEnvironmentId and auth data for the service you are authenticating with:

When using the generator you will notice that the services listed in the drop-down are limited to token-based services. For the reasons explained above, OAuth services are not included here.

The name given to the authentication you are creating is determined by you. This name will be visible in the Tray UI and can help you categorise authentications according to service and owner. You can also display it in your own app UI if it is ever needed.

Note also that, if you are the actual owners of the service and it uses standard password/token-based authentication, it is possible to pass extra custom fields into data in the above mutation. Please contact us if you would like to discuss this.

Note on connector version

You will also note that each connector contains multiple versions:

The version you choose should correspond to the version the connector is on in the Tray workflow builder. This is found by clicking on Show advanced settings for the Workflow connector step. You can then scroll back up to see the version, as per this SQS example:

Selecting the version is a necessary step to take because authentication details might change from one version of the Tray connector to the next - e.g. the service may ask for an extra key to be passed in the data field, or the acutal type of the authentication may change from token-based to OAuth or OAuth2.

In the vast majority of cases authentication does not change from one version to the next, so you will notice that the returned code snippet will most often stay exactly the same when you change versions in the drop-down.

Please also see our documentation on managing connector versions for some basic info on this topic.

Important note on formatting data

The json values passed in data must be in single line format, with " characters escaped with a slash as per the above example.

If you are importing an auth for your own OAuth-based service, scopes (as a simple list of strings such as scopes: ["pages_show_list", "leads_retrieval"]) can be used to define the exact read/write access an auth has to different components of the service. Your service OAuth documentation should provide the necessary details for scopes.

The payload for this mutation will return an authenticationId.

3 - Create the Solution Instance

Along with the externalId obtained from step 1, the authenticationId you have just obtained when creating the auth can be passed (as authId) using the authValues argument when using the createSolutionInstance API:

mutation {
createSolutionInstance(input: {
solutionId: "0dc02586-xxx-xxx-xxxx-cb98734578ef",
instanceName: "some instance name",
authValues: [{ externalId: "external_sqs_authentication", authId: "aaa67786-xxx-xxx-xxx-97dedd1519b3" }]
}) {
solutionInstance {

Note that the externalId of both authValues and configValues is case sensitive. For example if, in the UI at step 1 above, you have set the externalId as 'external_sqs_authentication' but then create the Solution Instance with 'External_SQS_Authentication' then the mutation will fail.

4 - Enable the Solution Instance

Don't forget that once a Solution Instance has been created, the final step in activating it for an End User is to use the updateSolutionInstance mutation to set the status to 'enabled'.