# Raw HTTP (Token) Quickstart

Learn how to deploy a token-based service connector with a single Raw HTTP operation using the TMDB 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 token based service connector with a single Raw HTTP operation.

We will be using [TMDB (The Movie Database) API](https://developer.themoviedb.org/docs/getting-started) as our Token based 3rd party service.

Follow the steps below to achieve this:

## 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. Create a service

***

> **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 TMDB example), you will need a service for it.

Services can be created on the Tray UI. Go to the **services** tab on the app and click new service:

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

Now add service details on the page as shown below:

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

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

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

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

> **Info:** This quickstart uses a **token** 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. OAuth2 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 TMDB uses token auth, we need to import `TokenOperationHandlerAuth` from the `cdk-dsl`

```js
import { TokenOperationHandlerAuth } 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 = TokenOperationHandlerAuth<UserAuth, AppAuth>
```

Since TMDB uses a token auth, we can leave `AppAuth` blank and token can be added under `UserAuth`.

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

```typescript
import { TokenOperationHandlerAuth } 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 TmdbAuth = TokenOperationHandlerAuth<UserAuth, AppAuth>;
```

### 3.2 GlobalConfig.ts

You need to configure the auth in global configs so that it is applied to all operations (including Raw HTTP)

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 { TmdbAuth } from "./TmdbAuth";

export const globalConfigHttp = OperationGlobalConfigHttp.create<TmdbAuth>()
  .withBaseUrl((_ctx) => `https://api.themoviedb.org`)
  /* 
  * 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 from the 3rd party service.

Here is the screenshot of the panel configured to call [GET /3/movie/top\_rated](https://developer.themoviedb.org/reference/movie-top-rated-list)

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

## Next Steps

You can start building individual operations on the connector now.

We recommend following the [Single HTTP quickstart](https://tray.ai/documentation/developer/connector-development-kit/overview/quickstarts/single-http) first and then moving to [building section](https://tray.ai/documentation/developer/connector-development-kit/developing-connectors/authentications/auth-ts).