# Deploying a CDK connector using APIs

## Overview

You can deploy connectors built through CDK using the [Connector Deployment API](https://tray.ai/documentation/developer/platform-apis/deployments#endpoint-create-deployment).

## Prerequisites - API token

In order to deploy a connector, you will need an RBAC (Role Based Access Control) API token, you can  on how to create one.

After deploying a connector using an API token, your connector will be owned by that token. This means you will need to use that same token to share that connector with yourself and any other users you want to issue access to.

The command to do this is `tray-cdk permissions add`. Check the reference [here](https://tray.ai/documentation/developer/connector-development-kit/reference/cli-reference).

### Deploying to different regions

Tray operates in 3 regions: US, EU and APAC. You will need to call the deployment API, using the region specific base URL and RBAC token, for each region you wish to use the connector in.

* US: <https://api.tray.io/>
* EU: <https://api.eu1.tray.io/>
* APAC: <https://api.ap1.tray.io/>

## Deployment flow

You need to prepare the following two things:

* The endpoint path: `https://api.tray.io/cdk/v1/deployments/connectors/${connector-name}/versions/${connector-version}/deploy-connector-from-source`

  * The hyphenated connector name is included in the URL path .e.g my-connector-name
  * The connector version number is included in the URL path .e.g 1.0

* The connector itself:
  * has been built with `tray-cdk connector build`, this will generate a .tray/connector.zip
  * the connector.zip has been base64 encoded
  * the base64 encoded string is set as the value for the `connectorSourceCode` property in the JSON payload(

You can follow these steps to fulfil the above needs:

> **Most linux/mac systems come pre-installed with the required commands \`base64\` and \`curl\`.**&#x20;

### 1. Build the connector

cd into your connector directory and build the connector, this will generate a \`.tray/connector.zip'

```cli
cd my-connector
tray-cdk connector build
```

### 2. base64 encode the connector zip

base64 encode the connector.zip to a string, set that string as the value for the JSON key `connectorSourceCode` and write the JSON to a file called `payload.json`

```cli
printf '{"connectorSourceCode": "%s"}' "$(base64 -i .tray/connector.zip)" > payload.json
```

### 3. POST to the deployment URL

Make a curl POST request to the deployment URL, including:

* the `connector name` and `version` in the path,
* the `Tray API token` in the headers,
* and the `payload.json` in the body

```cli
curl --location 'https://api.tray.io/cdk/v1/deployments/connectors/{connector-name}/versions/{connector-version}/deploy-connector-from-source' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json' \
--data-binary "@payload.json"
```

Once your connector code has passed preliminary validation you should recieve a 200 response with a body similar to the one below, this means your connector is now deploying.

```json
\{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387", // deployment-id
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying"
\}
```

If you instead recieved a body that also includes `"repeatDeployment": true` this means a deployment for the same connector is already in progress. Once your current deployment has completed you will be able to deploy again.

```json
\{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387", // deployment-id
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying",
  "repeatDeployment": true
\}
```

### 5. Check deployment status

You can check the status of the ongoing deployment by polling the following GET request, including your Tray API token, the connector name, version and deployment ID (which you get in the response after calling the deployment API like in the above step)

```cli
curl --location 'https://api.tray.io/cdk/v1/deployments/connectors/{connector-name}/versions/{connector-version}/{deployment-id}' \
--header 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
--header 'Content-Type: application/json'
```

You should expect a response similar to the one below with `"deploymentStatus": "Deploying"` if your connector is currently deploying:

```json
\{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387",
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deploying"
\}
```

Or you will recieve a `"deploymentStatus": "Deployed"` if it has finished deploying:

```json
\{
  "id": "3c5e4a2d-ad3a-58e9-8e2d-eff986f62387",
  "connectorName": "my-connector",
  "connectorVersion": "1.0",
  "deploymentStatus": "Deployed"
\}
```

### 6. Share connector with emails

> **You can't share connectors across different Tray organizations.** You can also use the [CDK CLI](https://tray.ai/documentation/developer/connector-development-kit/reference/cli-reference) to share connectors.

Since you used a RBAC token of an API user to deploy the connector, it is technically owned by the API user.

The connector must be shared with you / anyone else before you / them can see it on Tray UI.

Run the following command after replacing the **connector-name**, **connector-version**, and the **emails of Tray user accounts** who need to use the connector:

```cli
curl -i -X POST \
  'https://api.tray.io/cdk/v1/permissions/connectors/{connector-name}/versions/{connector-version}/share-with-emails' \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -d '\{
    "emails": [
      "john.doe@domain.com",
      "jane.doe@domain.com"
    ]
  \}'
```

In the example above, `john.doe@domain.com`, `jane.doe@domain.com` would be two users within the API user's Tray org.