> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Setting Up API Access for Amazon S3

> Prerequisites and API access every Amazon S3 Connector API guide needs

The Amazon S3 Connector API lets an unattended integration deliver the rows of a Narrative dataset as files into an S3 bucket you own. Narrative delivers each new batch as it lands, and can also deliver the batches from up to 30 days before you connect the dataset. A person signs in once to create an API key and once to set up the bucket, and the integration works from the API key after that.

Complete the [prerequisites](#prerequisites) and [set up API access](#set-up-api-access) on this page before you follow any Amazon S3 API guide. The guides are listed under **Guides** on the [Amazon S3 Connector](/reference/connectors/amazon-s3.md#guides) reference page.

## Prerequisites

| Prerequisite | Needed for |
| - | - |
| [API key](#api-key) | Everything |
| [S3 Connector installed](#s3-connector-installed) | Everything |
| [A profile for your bucket](#a-profile-for-your-bucket) | File delivery |

### API key

Create the key under **Settings → API Keys** with read and write on `datasets` and `connections`, write on `uploads`, and read on `installations`, `apps`, and `app_profiles`. See [API Keys](/account-settings/api-keys.md) for the procedure and the [Permissions Reference](/reference/security/permissions.md) for what each resource covers.

Create it from a shared team account rather than a personal login, so the integration keeps working when someone changes roles.

### S3 Connector installed

The S3 Connector is app `7`. Find your installation of it:

```bash theme={null}
curl -s "https://api.narrative.io/installations?app_categories=destination_connector" \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# find the record with "app_id": 7 and note its "id"
```

Record the installation ID. If no record has `"app_id": 7`, install the S3 Connector from the Narrative Marketplace.

### A profile for your bucket

A connector profile names one S3 bucket and the file format Narrative writes into it. You set up a profile once per bucket, in the Narrative UI, with access to the bucket's settings in AWS:

**1. Open the connector**

In Narrative, go to **Installed Apps**, select **S3 Connector**, and choose **Add profile**.

**2. Name the profile and bucket**

Enter a profile name, a description, and the name of the bucket Narrative delivers to.

**3. Apply the bucket policy in AWS**

Copy the bucket policy the wizard shows, and apply it in the AWS console under the bucket's **Permissions → Bucket policy**, or with `aws s3api put-bucket-policy`. The policy lets Narrative's delivery role write, list, and delete objects in the bucket. You can also fetch the policy over the API, as shown in [Get the bucket policy](#get-the-bucket-policy).

**4. Tag the bucket in AWS**

Add the tag the wizard shows to the bucket, under **Properties → Tags**. The tag is named `NARRATIVE_S3_CONNECTOR_ID`, and its value ties the bucket to your company.

**5. Test access**

Run the wizard's access test. Narrative writes, lists, and deletes a test object in the bucket and reads the tag.

**6. Choose the file format and save**

Choose CSV, TSV, JSON, or Parquet. For CSV or TSV, also set the delimiter, quote, and escape characters, and whether to include a header row. Choose **Save and finish**, and the profile is enabled and ready for connections.

Every request in the guide then uses the profile ID. [List your profiles](#list-your-profiles) shows how to look it up.

## Set up API access

The guide talks to two hosts, and each takes its own credential:

| Host | Base URL | Credential | Handles |
| - | - | - | - |
| Narrative API | `https://api.narrative.io` | Your API key | Datasets, uploads, connections, profiles |
| S3 connector | `https://aws-s3.narrativeconnectors.com` | An installation token | Bucket and file format of each profile, bucket policy |

### Get an installation token

The S3 connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from [S3 Connector installed](#s3-connector-installed):

```bash theme={null}
curl -s -X POST https://api.narrative.io/installations/{installation_id}/token \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"access_token": "<INSTALLATION_TOKEN>", "access_token_expires_in": 10799,
#    "refresh_token": "<REFRESH_TOKEN>", "refresh_token_expires_in": 86399}
```

Store `access_token` as `$INSTALLATION_TOKEN`. It lasts about three hours, so request a new one at the start of each run of your integration.

Confirm that both hosts answer:

```bash theme={null}
curl -s https://api.narrative.io/company-info/whoami \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": 1234}

curl -s https://aws-s3.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → [{"id": "<PROFILE_ID>", "status": "enabled", "bucket_name": "<BUCKET_NAME>", ...}]
```

Send the API key to `api.narrative.io` and the installation token to `aws-s3.narrativeconnectors.com`.

> [!TIP]
>
> API keys contain characters that shells mangle. Read the key from a file or an environment variable rather than pasting it inline.

### List your profiles

The Narrative API lists the profiles under your installation, with the status of each:

```bash theme={null}
curl -s https://api.narrative.io/installations/{installation_id}/profiles \
  -H "Authorization: Bearer $NIO_API_TOKEN"
```

```json theme={null}
{
  "records": [
    {
      "id": "<PROFILE_ID>",
      "name": "Example delivery bucket",
      "description": "Example delivery bucket",
      "status": "enabled",
      "app_id": null,
      "app_name": null,
      "tags": []
    }
  ]
}
```

The S3 connector returns the same profiles along with the bucket and file format of each:

```bash theme={null}
curl -s https://aws-s3.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
```

```json theme={null}
[
  {
    "id": "<PROFILE_ID>",
    "name": "Example delivery bucket",
    "description": "Example delivery bucket",
    "status": "enabled",
    "bucket_name": "<BUCKET_NAME>",
    "config": {
      "file_type": "csv",
      "header": true,
      "delimiter": ",",
      "quote": "\"",
      "escape": "\"",
      "sort_columns": true,
      "compression": null
    }
  }
]
```

To read one profile, call `GET /profiles/{profile_id}` on the connector, which returns the same shape. Use a profile whose `status` is `enabled`, and record its `id`.

### Get the bucket policy

The connector generates the bucket policy for a bucket name:

```bash theme={null}
curl -s https://aws-s3.narrativeconnectors.com/bucket/{bucket_name}/bucket-policy \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
```

```json theme={null}
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<NARRATIVE_DELIVERY_ROLE_ARN>" },
      "Action": ["s3:DeleteObject", "s3:PutObject"],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>/*"
    },
    {
      "Effect": "Allow",
      "Principal": { "AWS": "<NARRATIVE_DELIVERY_ROLE_ARN>" },
      "Action": ["s3:List*", "s3:GetBucketTagging"],
      "Resource": "arn:aws:s3:::<BUCKET_NAME>"
    }
  ]
}
```

Apply the policy exactly as the connector returns it, with Narrative's delivery role in `Principal`.

### Read the delivery settings schema

Each connection carries delivery settings for the connector's `delivery` interface. The schema lists every setting with its type and description:

```bash theme={null}
curl -s https://api.narrative.io/apps/7/interfaces/delivery \
  -H "Authorization: Bearer $NIO_API_TOKEN"
# → {"id": "delivery", "app_id": 7, "metadata": {"tags": ["s3"], ...},
#    "schema": {"properties": {"bucket_prefix": {...}, "historical_data_enabled": {...}, ...}, ...}}
```

The connector serves the same schema at `https://aws-s3.narrativeconnectors.com/interfaces/delivery`, with no credential. [What the connection does](/reference/connectors/amazon-s3.md#api-connection-settings) explains each field.

## Connection settings

For the `quick_settings` each connection accepts and how a delivery treats existing and new rows, see **API connection settings** on the [Amazon S3 Connector](/reference/connectors/amazon-s3.md#api-connection-settings) reference page.

## Related content

> **[Amazon S3 Connector](/reference/connectors/amazon-s3.md)**
>
> Supported file formats and delivery options

> **[Connector Interfaces](/concepts/data-activation/connector-interfaces.md)**
>
> Why a dataset connects to an interface rather than a connector

> **[API Keys](/account-settings/api-keys.md)**
>
> Create and rotate keys for programmatic access


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.