Users

Users are the end users of your integrations

Get users (master token)

post/

Get all users including their name, id, and externalUserId.

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The query accepts a filter key criteria which can take in following fields:

field	Notes
id	This is generated by Tray when you create a end user using Mutations/Users/Create New User
externalUserId	This will be provided by you upon the time of creation. It is the unique Id of the user in your own app and hence a mapping is created between your end user and their corresponding Tray user
name	This will be provided by you upon the time of creation. It is the name of the end user in your own app
isTestUser	This will be provided by you upon the time of creation. This is a boolean flag that tells whether the user is billable or not

Here are some sample queries:

Get all users

query {
    users {
        edges {
            node {
                name
                id
                externalUserId
                isTestUser
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get user by ID

query { users (criteria: {userId: "13b3ab9c-XXXX-XXXX-XXXX-c4dd07fbbfa4"}){ edges { node { name id externalUserId } cursor } pageInfo { hasNextPage endCursor hasPreviousPage startCursor } } }

Get user by externalID

query {
    users ( criteria: { externalUserId: "my-external-user-id" } ){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get user by name

query {
    users ( criteria: { name: "Billy Bluehat" } ){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get test users

query {
    users ( criteria: { isTestUser: true } ){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get test user by name

query {
    users ( criteria: { isTestUser: true, name: "Billy Bluehat" } ){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

The query also accepts following pagination parameters:

parameter	Notes
first	number to filter the first `n` users from response
last	number to filter the last `n` users from response
before	pagination parameter to go to previous page of response
after	pagination parameter to go to next page of repsonse

Here are some sample queries:

Get users after cursor

query {
    users (after: "MTNiM2FiOWMtZTIyMi00NzM5LWE2OWItYzRkZDA3ZmJiZmE0"){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get first 2 users

query {
    users (first: 2){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

Get first 5 users after cursor

query {
    users (first: 5, after: "MTNiM2FiOWMtZTIyMi00NzM5LWE2OWItYzRkZDA3ZmJiZmE0"){
        edges {
            node {
                name
                id
                externalUserId
            }
            cursor
        }
        pageInfo {
          hasNextPage
          endCursor
          hasPreviousPage
          startCursor
        }
    }
}

It can return the following data:

Returned Data	subfields	Notes
name
id		Tray ID of the user
externalUserId		unique id for the user in your database
cursor		used for pagination
pageinfo	hasNextPage, endCursor, hasPreviousPage, startCursor	used for pagination

SecuritybearerAuth

Request

Responses

200

OK - Returns the end users from your embedded org

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "query {\n    users {\n        edges {\n            node {\n                name\n                id\n                externalUserId\n            }\n            cursor\n        }\n        pageInfo {\n          hasNextPage\n          endCursor\n          hasPreviousPage\n          startCursor\n        }\n    }\n}",
    "variables": {}
  }'

Response samples

application/json

{"data": {"users": {"edges": [{"node": {"name": "Michael Scott",
"id": "13b3ab9c-XXXX-XXXX-XXXX-XXXX07fbbfa4",
"externalUserId": "668341a0-XXXX-XXXX-XXXX-XXXX5c9ba02b"
},
"cursor": "MTNiM2FiOWMtZTIyMi00NzM5LWE2OWItYzRkZDA3ZmJiZmE0"
},
{"node": {"name": "Dwight Schrute",
"id": "1a71daf1-97ba-4036-a5cc-dbb4ab325a55",
"externalUserId": "323442a0-XXXX-XXXX-XXXX-XXXX5c9ba02b"
},
"cursor": "XXXXXXXXZjEtOTdiYS00MDM2LWE1Y2MtZGJiNGFiMzI1YTU1"
}
],
"pageInfo": {"hasNextPage": false,
"endCursor": "XXXXXXXXZjEtOTdiYS00MDM2LWE1Y2MtZGJiNGFiMzI1YTU1",
"hasPreviousPage": false,
"startCursor": "XXXXXXXXOWMtZTIyMi00NzM5LWE2OWItYzRkZDA3ZmJiZmE0"
}
}
}
}

Create new user (master token)

post/

Create a new external user of your Embedded application.

To exclude users from billing you can mark them as test users (see our End users page for more info).

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The mutation accepts the following as inputs:

Input	Required	Note
name	Yes
externalUserId	Yes	can be used to link the End User to an ID you already have for them in your external database. It's important to be able to access key info, such as contact email, you may have stored in your external system. Example: dealing with Expired Auths
isTestUser	No	Boolean value that defaults to `true` (billable user) if you don't pass it. A test user allows you to create Solution Instances and run test data for a user without incurring any charges. This is useful for end to end testing. Please read our end users page here.
clientMutationId	No	Only relevant if using the Relay GraphQL client

Here is an example mutation:

Create new user

mutation {
  createExternalUser(input: { 
    name: "Dwight Schrute",
    externalUserId: "my-apps-user-id-for-dwight"
  }) {
    userId
  }
}

Create new user with clientMutationId

mutation {
  createExternalUser(input: { 
    name: "Dwight Schrute",
    externalUserId: "my-apps-user-id-for-dwight",
    clientMutationId: "some-mutation-id" #OPTIONAL - only needed for legacy Relay & Apollo clients
  }) {
    userId
    clientMutationId #OPTIONAL
  }
}

It can return the following data:

Returned Data	Notes
userId	Tray Id of the user
clientMutationId	Only relevant if using the Relay GraphQL client

SecuritybearerAuth

Request

Responses

200

OK - Returns the userId of the newly created user

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation($name: String!, $externalUserId: String!) {\n  createExternalUser(input: { \n      name: $name, \n      externalUserId: $externalUserId  \n    }) {\n      userId\n  }\n}",
    "variables": {
      "name": "Dwight Schrute",
      "externalUserId": "my-apps-user-id-for-dwight"
    }
  }'

Response samples

application/json

{"data": {"createExternalUser": {"userId": "d235e0b1-XXXX-XXXX-XXXX-7d165cdf4171"
}
}
}

Create user token (master token)

post/

Create an accessToken for a given userId

A user token allows access to the APIs which require a user token (Create Solution Instance, Get Solution Instances, Create User Auth etc.) and should be passed as a Bearer in the Authorization header when calling those APIs.

Note: This access token expires after 2 days

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The mutation accepts the following as inputs:

Input	Required	Notes
userId	Yes	obtained when creating a user (Mutations/Users/Create New User) or getting users (Queries/Users/Get Users)
clientMutationId	No	Only relevant if using the Relay GraphQL client

Here is an example mutation:

Create user token

mutation {
  authorize(input: {
      userId: "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6"
  }) {
    accessToken
  }
}

Create user token with clientMutationId

mutation {
  authorize(input: {
      userId: "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6",
      clientMutationId: "my-mutation-id" #OPTIONAL - only needed for legacy Relay & Apollo clients
  }) {
    accessToken
    clientMutationId #OPTIONAL
  }
}

It can return the following data:

Returned Data	Notes
accessToken	a persistent token (valid for 2 days) that should be securely stored in your application. Allows access to the APIs which require a user token (e.g. createSolutionInstance)
clientMutationId	Only relevant if using the Relay GraphQL client

SecuritybearerAuth

Request

Responses

200

OK - Returns the accessToken of the user

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($userId: ID!) {\n  authorize(input: {\n      userId: $userId\n  }) {\n    accessToken\n  }\n}",
    "variables": {
      "userId": "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6"
    }
  }'

Response samples

application/json

{"data": {"authorize": {"accessToken": "3346c4c957b74ca2a803dacf1485816d3fedde3a54b547b997cd64b72375a9d4"
}
}
}

Create Auth/Config dialog Authorization Code (master token)

post/

Creates an authorization code that is used to configure config wizard URL or auth-only dialog URL. Refer this page on how it's used.

Note: This is a one-time use code which expires after 5 minutes

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The mutation accepts the following as inputs:

Input	Required	Notes
userId	Yes	obtained when creating a user (Mutations/Users/Create New User) or getting users (Queries/Users/Get Users)
clientMutationId	No	Only relevant if using the Relay GraphQL client

Here is an example mutation:

Create Config Wizard Auth Code

mutation {
  generateAuthorizationCode( input: {
    userId: "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6"
  }) {
    authorizationCode
  }
}

Create Config Wizard Auth Code with clientMutationId

mutation {
  generateAuthorizationCode( input: {
    userId: "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6",
    clientMutationId: "my-mutation-id" #OPTIONAL - only needed for legacy Relay & Apollo clients
  }) {
    authorizationCode
    clientMutationId #OPTIONAL
  }
}

It can return the following data:

Returned Data	Notes
authorizationCode	this is required to activate the Configuration Wizard
clientMutationId	Only relevant if using the Relay GraphQL client

SecuritybearerAuth

Request

Responses

200

OK - Returns the one time use authorizationCode for the user

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation ($userId: ID!) {\n  generateAuthorizationCode( input: {\n    userId: $userId\n  }) {\n    authorizationCode\n  }\n}",
    "variables": {
      "userId": "d869ec65-XXXX-XXXX-XXXX-ac5c1a3958b6"
    }
  }'

Response samples

application/json

{"data": {"generateAuthorizationCode": {"authorizationCode": "a61eb70884f9af554a941876a66560b4bbfe48cc"
}
}
}

Update user (master token)

post/

Can be used to mark a user as a test user allowing you to create Solution Instances and run test data for a user without incurring any charges (see our End users page for more info)

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The mutation accepts the following as inputs:

Input	Required	Note
id	Yes
isTestUser	Yes	Booelan value. A test user allows you to create Solution Instances and run test data for a user without incurring any charges

Here is an example mutation:

Update to test user

mutation {
   updateExternalUser(input: {
      userId: "53824943-XXXX-XXXX-XXXX-088aee14038e",
      isTestUser: true
  }) {
    user{
            name
            id
            externalUserId
            isTestUser
        }
  }
}

Update to test user with clientMutationId

mutation {
   updateExternalUser(input: {
      userId: "53824943-XXXX-XXXX-XXXX-088aee14038e",
      isTestUser: "true",
      clientMutationId: "some-mutation-id" #OPTIONAL - only needed for legacy Relay & Apollo clients
  }) {
    user{
            name
            id
            externalUserId
            isTestUser
      clientMutationId #OPTIONAL
        }
  }
}

It can return the following data:

Returned Data	Notes
name
id
externalUserId
isTestUser

SecuritybearerAuth

Request

Responses

200

OK - Updates the user with the new data provided

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation  ($userId: ID!, $isTestUser: Boolean ){\n   updateExternalUser(input: {\n      userId: $userId,\n      isTestUser: $isTestUser\n  }) {\n    user{\n\t\t\tname\n\t\t\tid\n\t\t\texternalUserId\n\t\t\tisTestUser\n\t\t}\n  }\n}",
    "variables": {
      "userId": "53824943-XXXX-XXXX-XXXX-088aee14038e",
      "isTestUser": true
    }
  }'

Response samples

application/json

{"data": {"updateExternalUser": {"user": {"name": "Dwaight Schrute",
"id": "ad15b7ae-4c2d-4574-bf4f-5e8e1097a6e9",
"externalUserId": "test003",
"isTestUser": true
}
}
}
}

Delete user (master token)

post/

This mutation is used to delete a user from your Embedded application.

Note: Deleting a user will also disable and delete all Solution Instances associated with that user.

Required Token	Notes
Master	Obtained from the Tray app UI. Refer this.

The mutation accepts the following as inputs:

Input	Required	Notes
userId	Yes	obtained with Queries/Users/Get Users
clientMutationId	No	Only relevant if using the Relay GraphQL client

Here is an example mutation:

Delete user

mutation {
  removeExternalUser(input: {
      userId: "53824943-XXXX-XXXX-XXXX-088aee14038e"
    }) {
      clientMutationId # REQUIRED - must specify as return field, not required to provide this in mutation function
  }
}

Delete user with clientMutationId

mutation {
  removeExternalUser(input: {
      userId: "53824943-XXXX-XXXX-XXXX-088aee14038e", 
      clientMutationId: "someClientMutationId"
  }) {
      clientMutationId # REQUIRED - must specify as return field
  }
}

It can return the following data:

Returned Data	Notes
clientMutationId	while this data is only relevant if using the Relay GraphQL client, it is actually required here as currently this mutation does not return any other data

SecuritybearerAuth

Request

Responses

200

OK - Deletes the end user

401

Unauthorized

403

Forbidden

500

Internal Error

Request samples

curl

curl -i -X POST \
  https://tray.io/graphql \
  -H 'Authorization: Bearer <MASTER_TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "mutation {\n  removeExternalUser(input: {userId: $userId}) {\n      clientMutationId # REQUIRED - must specify as return field, not required to provide this in mutation function\n  }\n}",
    "variables": {
      "userId": "53824943-XXXX-XXXX-XXXX-088aee14038e"
    }
  }'

Response samples

application/json

{"data": {"removeExternalUser": {"clientMutationId": null
}
}
}