ToolJet/docs/versioned_docs/version-2.18.0/data-sources/s3.md

---
id: s3
title: Amazon S3
---

# Amazon S3

ToolJet can connect to Amazon S3 buckets and perform various operation on them.

## Connection

To add a new S3 source, go to the **Data sources manager** on the left sidebar of the app editor and click on `Add data source` button. Select **AWS S3** from the modal that pops up.

ToolJet supports connecting to AWS S3 using **IAM credentials**, **AWS Instance Profile** or **AWS ARN Role**. 

If you are using **IAM credentials**, you will need to provide the following details:

- **Region**
- **Access key**
- **Secret key**

It is recommended to create a new IAM user for the database so that you can control the access levels of ToolJet.

<div style={{textAlign: 'center'}}>

<img className="screenshot-full" src="/img/datasource-reference/aws-s3/iam.png" alt="aws s3 modal" width="600" />

</div>

To connect to AWS S3 using **AWS Instance Profile**, select the **Use AWS Instance Profile**. This will use the IAM role attached to the EC2 instance where ToolJet is running.
To access the metadata service of an ECS container and the EC2 instance, we use the WebIdentityToken parameter which is obtained from a successful login with an identity provider.

<div style={{textAlign: 'center'}}>

<img className="screenshot-full" src="/img/datasource-reference/aws-s3/awsinstance.png" alt="aws s3 modal" width="600" />

</div>

If you are using **AWS ARN Role**, you will need to provide the following details:

- **Region**
- **Role ARN**

<div style={{textAlign: 'center'}}>

<img className="screenshot-full" src="/img/datasource-reference/aws-s3/arn.png" alt="aws s3 modal" width="600" />

</div>

Click on **Test connection** button to verify if the credentials are correct and that the database is accessible to ToolJet server. Click on **Save** button to save the data source.

:::tip
You can now connect to **[different S3 Hosts using custom endpoints](/docs/how-to/s3-custom-endpoints)**.
:::

## Querying AWS S3

Click on `+` button of the **query manager** at the bottom panel of the editor and select the data source added in the previous step as the data source. Select the operation that you want to perform and click **Save** to save the query.

<div style={{textAlign: 'center'}}>

<img className="screenshot-full" src="/img/datasource-reference/aws-s3/operationsv2.png" alt="aws s3 query" />

</div>

Click on the **run** button to run the query. 

**NOTE**: Query should be saved before running.

:::tip
Query results can be transformed using transformations. Read our transformations documentation to see how: **[link](/docs/tutorial/transformations)**
:::

## Query operations

You can create query for AWS S3 data source to perform several actions such as:
  1. **[Read object](/docs/data-sources/s3#read-object)**
  2. **[Upload object](/docs/data-sources/s3#upload-object)**
  3. **[List buckets](/docs/data-sources/s3#list-buckets)**
  4. **[List objects in a bucket](/docs/data-sources/s3#list-objects-in-a-bucket)**
  5. **[Signed url for download](/docs/data-sources/s3#signed-url-for-download)**
  6. **[Signed url for upload](/docs/data-sources/s3#signed-url-for-upload)**

### Read object

You can read an object in a bucket by using this operation. It requires two parameters - **Bucket** name and **Key**.


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/readv2.png" alt="aws s3 read object" />

### Upload object

You can use this operation to upload objects(files) to your S3 bucket. It requires four parameters:
  1. **Bucket**: Specify the bucket name
  2. **Key**: Key of the object/file
  3. **Content type**: Specify file type such as text, image etc. 
  4. **Upload data**: File/object that is to be uploaded. 


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/uplobjv2.png"  alt="aws s3 upload"/>


### List buckets

This operation will list all the buckets in your S3. This does not require any parameter.


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/listbucketsv2.png" alt="aws s3 bucket" />


### List objects in a bucket

This operation will fetch the list of all the files in your bucket. It requires two parameters:
  1. **Bucket**: Bucket name (mandatory)
  2. **Prefix**: To limit the response to keys that begin with the specified prefix (optional)
  3. **Max keys**: The maximum number of keys returned in the response body (optional). Default value is 1000.
  4. **Offset**: The key to start with when listing objects in a bucket (optional). 
  5. **"Next Continuation Token"**: `Next Continuation Token` indicates Amazon S3 that the list is being continued on this bucket with a token. ContinuationToken is obfuscated and is not a real key (optional).


:::info
**Next Continuation Token**
For listing a bucket for objects that begin with a specific character or a prefix, then use the `Offset` parameter. For example, if you want to list all the objects that begin with `a`, then set the `Offset` parameter to `a`. Similarly, if you want to list all the objects that begin with `ab`, then set the `Offset` parameter to `ab`.

The `Next Continuation Token` is used to list the next set of objects in a bucket. It is returned by the API when the response is truncated. The results will contain `Next Continuation Token` if there are more keys in the bucket that satisfy the list query. To get the next set of objects, set the `Next Continuation Token` parameter and run the query again.
The results will continue from where the last listing finished.
:::


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/listobjectsv2.png" alt="aws s3 list object" />


### Signed url for download

The object owner can optionally share objects with others by creating a presigned URL, using their own security credentials, to grant time-limited permission to download the objects. For creating a presigned URL, the required parameters are:
  1. **Bucket**: name of the bucket for uploading the file
  2. **Key**: an object key
  3. **Expires in**: an expiration time of URL


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/urldownv2.png" alt="aws s3 signed download" />


### Signed url for upload

The presigned URLs are useful if you want your user/customer to be able to upload a specific object to your bucket, but you don't require them to have AWS security credentials or permissions. For creating a presigned URL, the required parameters are:
  1. **Bucket**: name of the bucket for uploading the file
  2. **Key**: an object key
  3. **Expires in**: an expiration time of URL
  4. **Content type**: the content type such as text, image etc.


<img className="screenshot-full" src="/img/datasource-reference/aws-s3/urluplv2.png" alt="aws s3 signed upload" />



:::info
We built an app to view and upload files to AWS S3 buckets. Check out the complete tutorial **[here](https://blog.tooljet.com/build-an-aws-s3-broswer-with-tooljet/)**.
:::