Core

Authentications

Authentications represent third party service auths that power the tray connectors.

If you were building an integration between Salesforce and Slack, you would need authentications for both Salesforce and Slack.

What's a Service Environment?

A Tray connector essentially exposes underlying third party APIs (ex. a Salesforce connector has a corresponding Salesforce service in Tray).

A Service environment can be treated as an instance of that service within Tray aginst which authentcations are created.

Hence, a Tray Authentication is created against a serviceEnvironment.

By default, every service has a default service environment called 'Production'.

For an OAuth service, an authentication created with default 'Production' service environment uses Tray's OAuth app. If you use your own OAuth app for creating the authentication, it would create another service environment.

We recommend using your own custom OAuth apps to whitelabel the auth dialog that's presented to the end users.

Create Authentication

This endpoint is non-billable.

Enables creation of user authentications in Tray.

This endpoint is for the import of existing authentications.

If you need your End Users to create new auths from scratch, you should use the Auth-only dialog

The key authentication data is passed in the credentials and userData fields.

The steps involved in creating an authentication are:

Obtain a user token
Use Get connectors to get the 'Service' name and version (not the 'Connector' name and version)
Pass the Service name and version to Get service environments to retrieve serviceEnvironmentId plus userData and credentials input schema requirements
Create authentication with this endpoint with the user token as bearer and passing the necessary serviceEnvironmentId userData and credentials

Request Examples

{
  "name": "string",
  "serviceEnvironmentId": "string",
  "userData": {},
  "credentials": {},
  "scopes": [
    "string"
  ],
  "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Response Examples

{
  "id": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Get Authentication

This endpoint is non-billable.

Retrieves metadata associated with a user authentication by its ID.

Returns auth id serviceEnvironmentId name and scopes.

Does not return sensitive data, such as tokens.

Response Examples

{
  "id": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  "name": "Example authentication",
  "serviceEnvironmentId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  "scopes": [
    "read",
    "write"
  ],
  "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Update Authentication

This endpoint is non-billable.

Update a user authentication stored in Tray using it's authenticaionId.

This endpoint doesn't support partial updates i.e. all fields in the request body are mandatory.

Request Examples

{
  "name": "string",
  "userData": {},
  "credentials": {},
  "scopes": [
    "string"
  ],
  "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Response Examples

{
  "id": "123exxxx-xxxx-xxxx-xxxx-xxxxxx614174",
  "name": "Example authentication",
  "serviceEnvironmentId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  "scopes": [
    "read",
    "write"
  ],
  "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Delete Authentication

This endpoint is non-billable.

Allows deletion of authentications using the authentication's id.

Response Examples

{
  "message": "string",
  "code": "string"
}

Get Full Authentication

This endpoint is non-billable.

Retrieves a user authentication by its ID, including sensitive data, such as tokens.

Can currently only be used by embedded end users, or by an API user on a shared workspace.

Please note that this endpoint returns all authentication data and is not redacted. This data will therefore appear in your workflow logs if called from within a workflow. This endpoint should only be used outside of the Tray workflow builder.

The organization Owner or an Admin can contact technical support to enable this endpoint.

Response Examples

{
  "id": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  "name": "Example authentication",
  "serviceEnvironmentId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  "userData": {
    "userId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
  },
  "credentials": {
    "accessToken": "XXXXX",
    "tokenType": "Bearer",
    "expiresIn": 3600
  },
  "scopes": [
    "read",
    "write"
  ],
  "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

List Service Environments

This endpoint is non-billable.

Gets all service environments for a given service name and version.

This endpoint is primarily used for retrieving the Service Environment id of your custom OAuth apps which you have deployed for whitelabelling purposes.

The service name and version must first of all be retrieved using Get connectors and then passed as query parameters in the above endpoint url.

The following is an example response from Mailchimp.

{
    "elements": [
        {
            "id": "42f51xxx-xxx-xxx-xxx-xxx0299c52",
            "title": "Production",
            "authenticationType": "oauth2",
            "userDataSchema": {},
            "credentialsSchema": {},
            "scopes": []
        },
        {
            "id": "c34exxx-xxx-xxx-xxx-xxxc97520e5",
            "title": "mailchimp acme oauth",
            "authenticationType": "oauth2",
            "userDataSchema": {},
            "credentialsSchema": {},
            "scopes": []
        }
    ]
}

The 'Production' environment is Tray's default environment which you use when creating a normal auth with Mailchimp in Tray.
The 'mailchimp acme oauth' environment is a custom OAuth app environment. The id userDataSchema and credentialsSchema from this are used to create the inputs for Create user authentication
The id is also required to build the auth-only dialog url to enabe End Users to create auths from scratch:

Response Examples

{
  "elements": [
    {
      "id": "228axxxx-xxxx-xxxx-xxxx-xxxxxxa244c1",
      "title": "Production",
      "authenticationType": "oauth2",
      "userDataSchema": {
        "advanced": [],
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "signing_secret": {
            "format": "password",
            "description": "Used in the slack trigger version 5.0 and later to verify slash commands",
            "type": "string",
            "title": "Slash command signing secret"
          }
        }
      },
      "credentialsSchema": {},
      "scopes": [
        {
          "scope": "calls:read",
          "description": "Allow apps to access information about ongoing and past Calls"
        },
        {
          "scope": "channels:history",
          "description": "Access user’s public channels"
        },
        {
          "scope": "channels:read",
          "description": "Access information about user’s public channels"
        },
        {
          "scope": "channels:write",
          "description": "Modify your public channels"
        },
        {
          "scope": "chat:write:bot",
          "description": "Send messages as tray.io"
        }
      ]
    }
  ]
}