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

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

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"
    ]
}
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

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

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"
    ]
}
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
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


 
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
Applicable for OAuth services only. An array of scopes attached to this auth are returned.


 
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"
    ]
}
Response samples 
application/json
{
  • "id": "123exxxx-xxxx-xxxx-xxxx-xxxxxx614174",
  • "name": "Example authentication",
  • "serviceEnvironmentId": "123e4567-aaaa-aaaa-aaaa-aaaaaa614174",
  • "scopes": [
    • "read",
    • "write"
    ]
}
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"
          }
        ]
      }
    ]
}