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

post/core/v1/authentications
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:

  1. Obtain a user token

  2. Use Get connectors to get the 'Service' name and version (not the 'Connector' name and version)

  3. Pass the Service name and version to Get service environments to retrieve serviceEnvironmentId plus userData and credentials input schema requirements

  4. Create authentication with this endpoint with the user token as bearer and passing the necessary serviceEnvironmentId userData and credentials

SecuritybearerAuth
Request
header Parameters
Authorization
string

This must be a user token in order to link the auth to the correct end user.
If master token is used, it creates the auth in your Tray admin account.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Request Body schema: application/json
required
name
required
string

Name for the auth which identifies End User, service, test, dev etc.

serviceEnvironmentId
required
string

Obtained using the Get service environments endpoint

object

Data regarding base url, company id, table id etc.
Input schema obtained using the Get service environments endpoint

object

Auth data (token, secret etc.) required to complete the auth
Input schema obtained using the Get service environments endpoint

scopes
Array of strings unique

Example: "scopes": ["chat:write", "channels:read"] or "scopes": ["chatter_api,", "openid"]
List of the scopes required for the auth to function
Available scopes can be retrieved with Get service environments

onPremAgentGroupId
string <uuid>
Responses
200

OK - Returns the authentication id required by the Call connector endpoint

Note that Tray only checks input schema and does not currently validate auths so e.g. an invalid API key may still return a successful result

Response Schema: application/json
id
required
string <uuid>

Authentication Id in Tray for the newly created auth

400

Invalid input - Use Get service environments to check the correct schema

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found - Use Get service environments to check the serviceEnvironmentId

429

Limit exceeded

500

Internal error

Request samples
application/json
{
  • "name": "Example authentication",
  • "serviceEnvironmentId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  • "userData": {
    • "region": "us"
    },
  • "credentials": {
    • "token": "example_token"
    },
  • "scopes": [
    • "read",
    • "write"
    ],
  • "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}
Response samples
application/json
{
  • "id": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}

Get Authentication

get/core/v1/authentications/{authentication-id}
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.

SecuritybearerAuth
Request
path Parameters
authentication-id
required
string <uuid>

Unique ID of the authentication in Tray

Example: 497f6eca-xxxx-xxxx-xxxx-53cbbbba6f08
header Parameters
Authorization
string

This can either be a your master token or the user token of the end user who owns the auth.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - Returns authentication details

Response Schema: application/json
id
required
string <uuid>

Unique id of the authentication - required by the Call connector endpoint

name
required
string

Name for the auth which identifies End User, service, test, dev etc.

serviceEnvironmentId
required
string

Identifies the service and environment the auth is for (e.g. Tray Slack OAuth app or your own Custom Slack OAuth app)

scopes
Array of strings unique

The permission scopes which describe the level of access this auth has to the service

onPremAgentGroupId
string <uuid>
400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found - No auth with matching id has been found or user does not have access

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "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

put/core/v1/authentications/{authentication-id}
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.

SecuritybearerAuth
Request
path Parameters
authentication-id
required
string <uuid>

Unique ID of the authentication in Tray

Example: 497f6eca-xxxx-xxxx-xxxx-53cbbbba6f08
header Parameters
Authorization
string

This can either be a your master token or the user token of the end user who owns the auth.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Request Body schema: application/json
required
name
required
string

Name of the auth in Tray (e.g. John Doe's Slack Auth 10th Oct)

object

Data regarding base url, company id, table id etc.
Input schema obtained using the Get service environments endpoint

required
object

Auth data (token, secret etc.) required to complete the auth
Input schema obtained using the Get service environments endpoint

scopes
Array of strings unique

Example: "scopes": ["chat:write", "channels:read"] or "scopes": ["chatter_api,", "openid"]
List of the scopes required for the auth to function
Available scopes can be retrieved with Get service environments

onPremAgentGroupId
string <uuid>
Responses
200
Response Schema: application/json
id
required
string <uuid>

Authentication Id in Tray for the updated auth

name
required
string

Authentication Id in Tray for the updated auth

serviceEnvironmentId
required
string

Authentication Id in Tray for the updated auth

scopes
Array of strings unique

Applicable for OAuth services only. An array of scopes attached to this auth are returned.

onPremAgentGroupId
string <uuid>
400

Invalid Input

401

Unauthorized

403

Forbidden

404

Not Found

429

Limit Exceeded

500

Internal Error

Request samples
application/json
{
  • "name": "Example authentication",
  • "userData": {
    • "region": "us"
    },
  • "credentials": {
    • "token": "example_token"
    },
  • "scopes": [
    • "read",
    • "write"
    ],
  • "onPremAgentGroupId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174"
}
Response samples
application/json
{
  • "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

delete/core/v1/authentications/{authentication-id}
This endpoint is non-billable.

Allows deletion of authentications using the authentication's id.

SecuritybearerAuth
Request
path Parameters
authentication-id
required
string <uuid>

Unique ID of the authentication in Tray

Example: 497f6eca-xxxx-xxxx-xxxx-53cbbbba6f08
header Parameters
Authorization
string

This can either be a your master token or the user token of the end user who owns the auth.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
204

No content - The authentication was deleted successfully

400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found - No auth with matching id has been found or user does not have access to delete

429

Limit exceeded

500

Internal error

Request samples
Response samples
text/html

List Service Environments

get/core/v1/services/{service-name}/versions/{service-version}/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:

SecuritybearerAuth
Request
path Parameters
service-name
required
string

Name of the service as obtained from Get connectors

Example: trello
service-version
required
integer <int32>

Version of the service as obtained from Get connectors
Note that this is the single int 'service' version not the decimal 'connector' version

Example: 2
header Parameters
Authorization
string

You can either pass your master token here or user token of an end user.

Example: Bearer 3fd74d349xxxxxxxxxxxxxxxxxxxxxxxxd90df521
Responses
200

OK - Returns an elements array which contains the input schema for Create user authentication

Response Schema: application/json
Array of objects (PublicServiceEnvironment)
400

Invalid input

401

Unauthorized - Verify the token validity

403

Forbidden

404

Not found - Service name or version not found or user does not have access

429

Limit exceeded

500

Internal error

Request samples
Response samples
application/json
{
  • "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"
          }
        ]
      }
    ]
}