# S3

{% hint style="info" %}
The following documentation is for **S3 v1.6.4**.
{% endhint %}

## Overview

Manages files and folders in AWS S3.

## Setup

The following integrations need to be connected to your Kognitos workspace:

* **S3**

### Steps

Follow these steps to connect the integration in Kognitos:

{% stepper %}
{% step %}
**Navigate**

Using the left navigation menu, go to **Integrations** → **Explore Integrations**.
{% endstep %}

{% step %}
**Find**

Search for the integration and click on it.
{% endstep %}

{% step %}
**Connect**

Click on <kbd>**Connect**</kbd> to add a connection to the integration.
{% endstep %}

{% step %}
**Configure**

Add a name for the connection. You'll be prompted for [**authentication**](#authentication) details if needed. Then, click on <kbd>**Connect**</kbd>.
{% endstep %}
{% endstepper %}

## Authentication

Use one of the following authentication methods to connect this integration in Kognitos. Each method has its own configuration requirements.

### Connect using AWS Access key ID, AWS Secret Access Key, AWS Region, AWS Role ARN and AWS External ID

Assumes a role using the provided AWS credentials.

| Label                 | Description                                                                | Type        |
| --------------------- | -------------------------------------------------------------------------- | ----------- |
| AWS Access key ID     | The AWS Access Key ID for the initial authentication.                      | `text`      |
| AWS Secret Access Key | The AWS Secret Access Key for the initial authentication.                  | `sensitive` |
| AWS Region            | The AWS Region for the initial authentication.                             | `text`      |
| AWS Role ARN          | The ARN of the role to assume.                                             | `text`      |
| AWS External ID       | An optional external ID that might be required by the role's trust policy. | `sensitive` |

### Connect using AWS Access key ID, AWS Secret Access Key and AWS Region

Connects to an API using the provided API key.

| Label                 | Description               | Type        |
| --------------------- | ------------------------- | ----------- |
| AWS Access key ID     | The AWS Access Key ID     | `text`      |
| AWS Secret Access Key | The AWS Secret Access Key | `sensitive` |
| AWS Region            | The AWS Region            | `text`      |

## Actions

The following actions are available in the **S3** integration:

### 1. Copy an item to a folder

Create a copy of an item in a folder.

### 2. Create a folder in another folder

Create a folder in another folder.

### 3. Delete an item

Delete an item.

### 4. Download a file

Get a file as a file object.

### 5. Get buckets from s3

Get buckets from AWS S3.

### 6. Get a file at a path

Get a reference to a file at a path.

### 7. Get a folder at a path

Get a reference to a folder at a path.

### 8. Get a root folder from a bucket

Get a reference to the root folder in a bucket.

### 9. Get some folder's items

Get items from a folder.

### 10. Move an item to a folder

Update an item's location to a folder.

### 11. Rename an item to a name

Update an item's name.

### 12. Upload a file to a folder

Create a file in a folder.

## Concepts

### S3 file reference

Represents a reference to a file in an S3 bucket.

| Field Name    | Description                                                                         | Type     |
| ------------- | ----------------------------------------------------------------------------------- | -------- |
| `bucket_name` | The name of the S3 bucket containing the file.                                      | `text`   |
| `file_path`   | The full path of the file within the bucket, including the file name and extension. | `text`   |
| `parent_path` | The path of the parent folder of the file.                                          | `text`   |
| `name`        | The name of the file.                                                               | `text`   |
| `e_tag`       | The ETag of the file.                                                               | `text`   |
| `s3_uri`      | The S3 URI of the file.                                                             | `text`   |
| `size`        | The size of the file in bytes.                                                      | `number` |

### S3 folder reference

Represents a reference to a folder in an S3 bucket.

| Field Name    | Description                                                                                                 | Type     |
| ------------- | ----------------------------------------------------------------------------------------------------------- | -------- |
| `bucket_name` | The name of the S3 bucket containing the folder.                                                            | `text`   |
| `folder_path` | The path of the folder within the bucket. Should end with a trailing slash ('/') to indicate it's a folder. | `text`   |
| `parent_path` | The path of the parent folder of the folder.                                                                | `text`   |
| `name`        | The name of the folder.                                                                                     | `text`   |
| `e_tag`       | The ETag of the folder.                                                                                     | `text`   |
| `s3_uri`      | The S3 URI of the folder.                                                                                   | `text`   |
| `size`        | The size of the folder in bytes.                                                                            | `number` |

### S3 bucket

Represents a S3 bucket.

| Field Name | Description           | Type   |
| ---------- | --------------------- | ------ |
| `name`     | Name of the S3 Bucket | `text` |