Tray Embedded / Building Integrations / User Management

User Management

Read first

Make sure you have read the following sections before proceeding:



An External User of your Embedded application is somebody who has Instances of your Solutions set up and configured for their own use.

Your users should be stored in your own user database, and when they are created using the createExternalUser API they will be stored in your Tray Embedded account.

They must be linked between these two databases using a common externalUserId, which is created in your database and then passed as a parameter when using the createExternalUser API.

Key data

  • id is the unique ID of the user which is returned when creating a new user

  • externalUserId is a unique id taken from your external user database, used to link them in the Tray Embedded database

  • accessToken is a user token which allows access to the APIs which require a user token. It should be stored securely in your application and expires after 2 days

  • authorizationCode is a one-time access code which allows a user to access the Configuration Wizard and configure a Solution Instance for their own use

  • isTestUser is a boolean attribute which, when set to true, allows you to create Solution Instances and run test data for a user without incurring any charges (see our Billing page for more info)

See our API reference docs for more complete information on data associated with End Users.

Viewing End Users in

In the Tray Embedded UI it is possible to view End Users and their activated Instances.


Creating test users

To exclude users from billing, you can mark them as test users. This way, You can take the role of an End user and test your solutions by creating Test users. This is useful as Test users aren't billed.

You can create test users using the createExternalUser mutation - by setting isTestUser as 'true'. To mark an existing user as a test user, you can toggle this setting using the updateExternalUser mutation.

You can also do this in the Tray admin UI:

mark test users

Test user has certain limitations on logs and concurrency.

  • The workflow logs are deleted after 72 hours. The executions aren't stopped and if a workflow execution takes more than 72 hours, new executions won't be impacted by an existing execution.

  • Low concurrency which results in reduced performance

A test user as the name indicates is not ideal for production integrations and should only be used for end to end testing. For production, you would ideally need logs after 72 hours and a higher concurrency for performance which normal end users have.

Test users must be used as per the Tray's acceptable usage policy and are subject to audits.

APIs involved

  • The GraphQL createExternalUser mutation is used to create a new External User. This will return a userId. A user can be marked as a test user allowing you to create Solution Instances and run test data for a user without incurring any charges (see our Billing page for more info)

  • The authorize mutation is used to create an access token for an External User, which is passed as a Bearer with user-specific APIs such as Create Solution Instance, Get Solution Instances and Create User Authentication. This token should be stored in your application expires after 2 days

  • The generateAuthorizationCode mutation is used to generate a one-time access code for the Config Wizard

  • The udpateExternalUser mutation can be used to toggle a user's test user setting

Considerations when choosing ‘End-user’ information


It is recommended that the externalUserId for each customer is set to match the internal id for them in your external database, to enable mapping between the two systems.

If you wish to associate an End User with a group (i.e. company / department) then the externalUserId can be linked to the internal id for that group in your database.

Connected topics

The next page in this section will take you through displaying Solutions for your End Users: