Mutations

Mutations affecting Users of your application

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 Billing 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 billing 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 Billing 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
}
}
}