> For the complete documentation index, see [llms.txt](https://docs.tryterra.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryterra.co/destinations/cloud-storage-s3-gcp.md).

# Cloud storage (S3, GCS, Azure Blob)

Write raw Terra payloads to an AWS S3, Google Cloud Storage or Azure Blob bucket, and find files by date, type and user.

Terra can dump raw data payloads directly into your cloud storage bucket. Supported providers: **AWS S3**, **Google Cloud Storage (GCS)**, and **Azure Blob Storage**. This page covers granting Terra write access, adding the destination, and the folder layout Terra writes.

## Before you begin

* A bucket in AWS S3 or GCS, or a container in Azure Blob Storage.

## Grant Terra write access

{% tabs %}
{% tab title="AWS S3" %}
Give Terra a role in your AWS account, or an access key. For a role, see [Role-based access](#role-based-access).

For an access key, [create an IAM user](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) and [attach a policy](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_change-permissions.html) granting `s3:PutObject` on your bucket. Terra needs nothing else: it never reads or deletes objects. If the bucket is encrypted with a customer-managed KMS key, also allow `kms:GenerateDataKey` and `kms:Decrypt` on that key.
{% endtab %}

{% tab title="GCS" %}
[Create a service account](https://developers.google.com/workspace/guides/create-credentials#service-account) and grant it the **Storage Object Admin** role (`roles/storage.objectAdmin`) on your target bucket. This role is required because Terra overwrites existing files on redelivery, which needs both `storage.objects.create` and `storage.objects.delete` permissions. Download the JSON credentials file.

You can grant the role via the console or with:

```bash
gsutil iam ch serviceAccount:YOUR_SA@YOUR_PROJECT.iam.gserviceaccount.com:objectAdmin gs://YOUR_BUCKET
```

{% endtab %}

{% tab title="Azure Blob" %}
Generate a [SAS URL](https://learn.microsoft.com/en-us/azure/storage/common/storage-sas-overview) for your storage account that grants write access to your target container.
{% endtab %}
{% endtabs %}

## Add the destination in Terra

On the [Connections page](https://dashboard.tryterra.co/dashboard/connections) in your Terra dashboard, click **Add New**, add the storage destination, and enter the details for your provider:

| Provider   | Details                                                                   |
| ---------- | ------------------------------------------------------------------------- |
| AWS S3     | **Bucket name**, **region**, **Access Key ID**, and **Secret Access Key** |
| GCS        | **Bucket name** and the credentials JSON file                             |
| Azure Blob | **SAS URL** and **container name**                                        |

### Terra checks access when you save

When you create an S3 destination, turn one on, or change its configuration, Terra first writes a small file, `terra-connection-check.json`, to the root of your bucket. It uses the same credentials as deliveries, whether that is a role or an access key. Every check overwrites that same key.

```json
{
  "type": "connection_check",
  "message": "Terra sent this to check it can deliver here. You can ignore or delete it.",
  "checked_at": "2026-11-10T09:30:00Z"
}
```

If the write fails, Terra doesn't save the change and names the setting to fix. Through the API, that is a `400` with an entry such as `config.bucket: this bucket doesn't exist`. If Terra can't reach AWS, the request returns a `503` and you can retry it. A destination saved turned off isn't checked, and a `?dry_run=true` request writes nothing.

If something in your account processes every new object in the bucket, have it skip `terra-connection-check.json`.

## Role-based access

Instead of an access key, you can let Terra assume a role in your AWS account. Terra assumes it through its own AWS identity, so there is no key to store or rotate. You create the role from Terra's CloudFormation template, and it can only write objects to the one bucket you name. It can't read, list or delete anything.

{% hint style="info" %}
The dashboard will offer this option soon. Until then, set it up through the [admin API](https://docs.tryterra.co/reference/admin-api/overview). The examples below use [`terra admin-api`](https://docs.tryterra.co/developer-tools/terra-cli/raw-requests) from the Terra CLI.
{% endhint %}

### Get your setup values

`GET /environments/{dev_id}/unified-api/destination-types` returns `aws_role_setup` on the `s3` type. It needs the `destinations:read` scope.

```bash
terra admin-api /environments/<DEV_ID>/unified-api/destination-types --jq '.data[] | select(.type == "s3") | .aws_role_setup'
```

| Field                 | What it is                                                                                                                 |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `external_id`         | The External ID Terra assumes your role with. It is unique to your Terra account and the same for every environment in it. |
| `terra_principal_arn` | Terra's AWS principal, the only identity your role trusts.                                                                 |
| `template_url`        | Terra's CloudFormation template.                                                                                           |
| `quick_create_url`    | Opens the AWS console's **Quick create stack** page with the template, `ExternalId` and `TerraPrincipalArn` filled in.     |

If `aws_role_setup` is missing, role-based access isn't available for that environment. Use an access key instead.

### Create the role

1. Sign in to the AWS account that owns the bucket, and open `quick_create_url`.
2. Set `BucketName` to your bucket's name. Leave `QueueArn` empty.
3. If the bucket is encrypted with a customer-managed KMS key, set `KmsKeyArn` to the key's ARN. Otherwise leave it empty.
4. Leave `ExternalId` and `TerraPrincipalArn` as they are. Terra only assumes the role with your account's External ID, so a stack with a different value won't work.
5. Acknowledge that the stack creates an IAM role, and create the stack.
6. When the stack is created, copy `RoleArn` from its **Outputs** tab. Paste it rather than typing it: the role's name ends in the UUID from the stack's ID, as in `arn:aws:iam::<ACCOUNT_ID>:role/TerraByoCloud-<STACK_UUID>`.

Terra only accepts roles named `TerraByoCloud-<name>`, which is what the template creates. To deploy the template with your own tooling, use `template_url` with the same parameters.

### Add the role to the destination

Put the `RoleArn` in the destination's `config` as `role_arn`, when you create the destination or with a `PATCH`. Both need the `destinations:write` scope.

```bash
terra admin-api /environments/<DEV_ID>/unified-api/destinations -X POST --body '{
  "type": "s3",
  "config": {
    "bucket": "<BUCKET_NAME>",
    "region": "<REGION>",
    "role_arn": "<ROLE_ARN>"
  }
}'
```

A destination uses a role or an access key, not both. To move an existing destination from an access key to the role, clear the key in the same request:

```bash
terra admin-api /environments/<DEV_ID>/unified-api/destinations/<DESTINATION_ID> -X PATCH --body '{
  "config": {
    "role_arn": "<ROLE_ARN>",
    "access_key_id": null,
    "secret_access_key": null
  }
}'
```

To go back to an access key, send both keys with `"role_arn": null`. Saving runs the [access check](#terra-checks-access-when-you-save), so a role Terra can't assume or write with is refused before any delivery uses it.

## What Terra writes

All cloud storage destinations use the same folder structure:

```
2022-03-16/
  {event_type}/
    {user_id}-{timestamp}.json       # Auth/misc events
  {data_type}/
    {user_id}-{start_time}.json      # Data events (activity, sleep, etc.)
```

For example:

```
2022-03-16/auth/abc123-2026-03-12T14:30:00Z.json
2022-03-16/activity/abc123-2026-03-12T06:00:00Z.json
2022-03-16/sleep/abc123-2026-03-11T22:00:00Z.json
```

* **Data events** (activity, sleep, body, etc.) are placed under a folder named after the data type, with each file named `{user_id}-{start_time}.json`.
* **Auth and other events** are placed under a folder named after the event type, with each file named `{user_id}-{timestamp}.json`.
* The `2022-03-16` prefix corresponds to the API version.

{% hint style="info" %}
**FIT files (S3 only):** For activity data that includes raw FIT files, Terra uploads both the JSON payload and the original `.fit` file alongside it (e.g. `2022-03-16/activity/abc123-2026-03-12T06:00:00Z.fit`).
{% endhint %}

## Next steps

* [User authentication](/unified-api/authentication-flow.md): link a user's wearable so events start flowing.
* [Event delivery](/destinations/events.md): see what each delivery status means and how retries work.
* [Health data events](/unified-api/receiving-data-updates.md): process the data Terra delivers.
