Raw HTTP (OAuth2) Quickstart

Raw HTTP operation allows you to call any endpoint of the underlying service through the Builder UI without having to build individual operations.

This is a simple way to test if you have configured the service correctly and the auth setup is working.

This guide will show you the steps to deploy a OAuth2 service connector with a single Raw HTTP operation.

We will be using Dropbox API as our OAuth2 based 3rd party service.

Pre-requisite

1. Follow the Introduction to install the CDK and initialize a connector project.
2. You have obtained a namespace . You won't be able to deploy the connector otherwise. To get a namespace , please create a support ticket .

1. Service creation

Services are used by connectors for handling authentications on Tray platform.

Hence if your connector needs a auth (which it does in our Dropbox example), you will need a service for it. Before you create a service on Tray UI, you will need an OAuth app.

1.1 Creating OAuth app

Go to Dropbox app console and create a new app.

Add https://auth.tray.io/oauth2/token as redirect Uri as shown below:

Copy the App key and App secret from this screen as it will be needed when creating the service on Tray.

Select files.metadata.read scope in the permissions tab as shown below:

1.2 Creating a Tray service

Go to the services tab on the app and click new service:

Now add service details on the page as shown below:

Use App key and App secret from previous step for Client ID and Client secret.

Now save the service. Upon saving, you will see the unique service name.

Copy the unique service name (j5DAHD2Y3Q3Kq_dropbox-cdk in the screeenshot above). This will be required in the deployment step.

2. Delete the test operation

Connector projects are initialized with a dummy test operation get_post. Delete the get_post operation folder from src directory.

3. Add authentication

Upon initializing the connector, the following two files were created in root of src folder:

1. Auth.ts : This will define the types for auth that is passed with the request.
2. GlobalConfig.ts : This will define the global configs e.g. baseUrl, custom Headers etc. that will remain same with every request.

3.1 Auth.ts

Since Dropbox uses OAuth2, we need to import Oauth2OperationHandlerAuth from the cdk-dsl

import { Oauth2OperationHandlerAuth } from "@trayio/cdk-dsl/connector/operation/OperationHandler";

All auth types need to follow a predefined schema as shown here:

export type UserAuth = {
  // user credentials
}

export type AppAuth = {
  // OAuth app credentials
}

export type [ConnectorName]Auth = [AuthType]OperationHandlerAuth<UserAuth, AppAuth>

As per API docs, we only need a token to call the List folders endpoint.

Here's the full Auth.ts file for reference:

import { Oauth2OperationHandlerAuth } from "@trayio/cdk-dsl/connector/operation/OperationHandler";

export type UserAuth = {
  access_token: string // you can call this property anything e.g. token, auth_token etc.
};

export type AppAuth = {};

export type DropboxCdkAuth = Oauth2OperationHandlerAuth<UserAuth, AppAuth>;

3.2 GlobalConfig.ts

Lastly, you can define some global configs that will be applied to all operations.

This file uses OperationGlobalConfigHttp to create a Global config object.

The object provides several functions that can be used to add configs, e.g.:

• withBaseUrl function can be used to define a baseUrl .
• withBearerToken can be used to configure a Bearer auth.

Here's the full GlobalConfig.ts file for your reference:

import { OperationGlobalConfigHttp } from "@trayio/cdk-dsl/connector/operation/OperationGlobalConfig";
import { DropboxCdkAuth } from "./DropboxCdkAuth";

export const globalConfigHttp = OperationGlobalConfigHttp.create<DropboxCdkAuth>()
  .withBaseUrl((_ctx) => `https://api.dropboxapi.com/2`) // v2 of Dropbox API
  /* 
  * Notice how `access_token` is accessed from `auth` below.
  * Name of the property (`access_token` in this case) would depend on what you used in the auth.ts file
  */
  .withBearerToken((ctx) => ctx.auth!.user.access_token);

4. Enabling raw-http

Raw HTTP is enabled by default.

To verify, navigate to the connector.json file in the root of the connector project.

You will find the following line: "rawHttp": {"enabled": true} in the file.

This means, once deployed the connector will have rawHttp operation enabled on the Tray Builder UI.

5. Deploy the connector

The connector is ready to be deployed. Follow the steps as shown on the Deployment API guide.

6. Test on Tray UI

Add the connector to a existing / new workflow.

You can configure the properties panel to call any endpoint you wish.

Here is the screenshot of the panel configured to call List folders endpoint.