# Raw HTTP (OAuth2) Quickstart

Deploy an OAuth2 service connector with a single Raw HTTP operation using the Dropbox API

> **Info:** Follow [composite quickstart](https://tray.ai/documentation/developer/connector-development-kit/overview/quickstarts/composite) if you are building up a Helper / Utility connector.

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](https://developers.dropbox.com/oauth-guide) as our OAuth2 based 3rd party service.

## Pre-requisite

***

Follow the [Introduction](https://tray.ai/documentation/developer/connector-development-kit/overview/introduction) to install the CDK, obtain a `namespace` and initialize a connector project.

## 1. Service creation

***

> **You do not need a Custom Service if you are creating a helper / utility connector that doesn't need user auth.** 

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:

![dropbox-oauth-app](https://tray.ai/documentation/images/developer-portal/dropbox_oauth_app_configuration.png)

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:

> **Info:** `files.metadata.read` scope is needed for the Dropbox  endpoint.We will test Raw HTTP operation with this endpoint once the connector is deployed.You can select more scopes as needed if you want the Raw HTTP operation to work with other endpoints.

![dropbox-oauth-app-permissions](https://tray.ai/documentation/images/developer-portal/dropbox_oauth_app_scopes.png)

### 1.2 Creating a Tray service

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

![dropbox-service](https://tray.ai/documentation/images/developer-portal/new_service_app_ui.png)

Now add service details on the page as shown below:

![dropbox-service-before-save](https://tray.ai/documentation/images/developer-portal/dropbox-service-before-save.png)

Use `App key` and `App secret` from [previous step](#11-creating-oauth-app) for Client ID and Client secret.

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

![dropbox-service-name](https://tray.ai/documentation/images/developer-portal/dropbox-service-name.png)

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

> **Info:** This quickstart uses a **OAuth2** based service. Refer to the [Custom services](https://tray.io/documentation/tray-uac/connectivity/custom-services/introduction/) page for guidance on creating other types of services (e.g. Token etc.)

## 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

> **This file just defines the type of Auth that your service needs, all the authentication logic is handled by Tray i.e. you don't need to write the logic to generate / refresh auth tokens.** 

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

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

> **CDK supports a variety of auth types including Token, OAuth1 and OAuth2.** Here's the list for reference:- TokenOperationHandlerAuth - For [token based services](https://www.okta.com/uk/identity-101/what-is-token-based-authentication/)
> - Oauth1OperationHandlerAuth - For [OAuth1](https://support.smartbear.com/readyapi/docs/requests/auth/types/oauth1/about.html) based services. Not a lot of services support OAuth1. [Here's](https://api.smugmug.com/api/v2/doc/tutorial/authorization.html) one that does.
> - Oauth2OperationHandlerAuth - For [OAuth2 Authorization Code grant type](https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/)
> - Oauth2PasswordOperationHandlerAuth - For [OAuth2 Password grant type](https://www.oauth.com/oauth2-servers/access-tokens/password-grant/)
> - Oauth2ClientCredentialsOperationHandlerAuth - For [OAuth2 Client Credentials grant type](https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/)

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

```js
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  endpoint.

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

```typescript
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:

```typescript
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);
```

> **Info:** Notice the `!` sign in `ctx.auth!.user.access_token` above. This tells the Typescript compiler that `ctx.auth` is non-null. Read more about Non-null assertion operator .

## 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](https://tray.ai/documentation/developer/connector-development-kit/deploying-connectors/deploy-using-api).

## 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  endpoint.

![raw-http-test-ui](https://tray.ai/documentation/images/developer-portal/raw-http-test-ui.png)