> ## 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 Reddit

> Prerequisites and API access every Reddit Connector API guide needs

The Reddit Connector API lets an unattended integration deliver hashed identifiers into Custom Audiences in your Reddit Ads account. You sign in to Narrative once to create an API key, and you connect your Reddit Ads account once. The integration works from the API key after that.

To deliver to a Reddit Ads account that someone else owns, such as a client's, send that person a [partner invite](/guides/connectors/reddit/connect-account-api.md). They connect their account, and you deliver to it the same way.

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

## Prerequisites

What you need depends on the guide you follow:

| Prerequisite | Custom Audiences | Partner invites |
| - | :-: | :-: |
| [API key](#api-key) | ✓ | ✓ |
| [Reddit Connector installed](#reddit-connector-installed) | ✓ | ✓ |
| [A connected Reddit profile](#a-connected-reddit-profile) | ✓ | |
| [A Reddit ad account on the profile](#list-your-ad-accounts) | ✓ | |

### API key

Create the key under **Settings → API Keys** with these permissions:

* Read and write on `datasets` and `connections`
* Write on `uploads`
* Read on `installations`

Add read and write on `webhooks` if you want delivery notifications. 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.

### Reddit Connector installed

The Reddit Connector is app `23`. 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": 23 and note its "id"
```

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

### A connected Reddit profile

A connector profile holds the Reddit authorization that every delivery uses. One profile reaches every ad account that the approving Reddit user can manage.

To deliver to your own Reddit Ads account, create a profile and approve Narrative on Reddit once, as described in [Connect your Reddit Ads account](#connect-your-reddit-ads-account). To deliver to an account someone else owns, [invite a partner](/guides/connectors/reddit/connect-account-api.md) instead. The partner's approval creates the profile.

## Set up API access

The guides talk 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, webhooks |
| Reddit connector | `https://reddit.narrativeconnectors.com` | An installation token | Profiles, ad accounts, invites, Reddit authorization |

### Get an installation token

The Reddit connector authenticates requests with an installation token, which you get by exchanging your API key. Use the installation ID from [Reddit Connector installed](#reddit-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://reddit.narrativeconnectors.com/profiles \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<PROFILE_ID>", "created_at": "2026-09-22T10:40:00Z",
#    "name": "Example Brand", "status": "enabled",
#    "updated_at": "2026-09-22T10:47:00Z"}]}
```

Send the API key to `api.narrative.io` and the installation token to `reddit.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.

### Connect your Reddit Ads account

Connect your Reddit Ads account once. Every delivery after that runs from your API key.

**1. Create a profile**

In Narrative, go to **Installed Apps → Reddit Connector**. In the **Profiles** tab, click **Add profile**, enter a profile name, and click **Create profile**.

**2. Approve Narrative on Reddit**

Click **Connect to Reddit**, sign in to the Reddit account that manages your ad accounts, and click **Allow**. The profile shows **Connected** once Reddit confirms.

[Setting Up the Reddit Connector](/guides/connectors/reddit/setting-up.md) covers these steps in more detail.

To approve Narrative from your integration instead of clicking **Connect to Reddit**, request an authorization link for the profile. [Find your profile](#find-your-profile) shows how to get its ID:

```bash theme={null}
curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/authorize \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"url": "https://www.reddit.com/api/v1/authorize?client_id=<CLIENT_ID>&redirect_uri=https://reddit.narrativeconnectors.com/reddit/callback&response_type=code&duration=permanent&scope=adsread+adsedit&state=<STATE>",
#    "expires_at": "2026-10-04T15:31:00Z"}
```

Open the `url` in a browser before `expires_at`, sign in to Reddit, and approve Narrative. The profile then uses your Reddit authorization.

### Find your profile

`GET /profiles` lists every Reddit profile in your company. To read one:

```bash theme={null}
curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "2026-09-22T10:40:00Z",
#    "name": "Example Brand", "status": "enabled",
#    "updated_at": "2026-09-22T10:47:00Z"}
```

Use a profile whose `status` is `enabled`. Record its `id`.

### List your ad accounts

Audiences are created under a Reddit ad account. List the ad accounts the profile can deliver to:

```bash theme={null}
curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}
```

Reddit ad account IDs start with `a2_`. To read one ad account:

```bash theme={null}
curl -s https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/{ad_account_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}
```

When the Reddit user gains access to another ad account after connecting the profile, reload the profile's ad accounts from Reddit:

```bash theme={null}
curl -s -X POST https://reddit.narrativeconnectors.com/profiles/{profile_id}/ad-accounts/refresh \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AD_ACCOUNT_ID>", "name": "Example Ad Account"}]}
```

The response lists every ad account on the profile after the reload.

## Connection settings

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

## Delivery notifications

The Reddit Connector reports each delivery as an app webhook event. Subscribe a webhook to app `23` to receive them:

```bash theme={null}
curl -s -X POST https://api.narrative.io/webhooks \
  -H "Authorization: Bearer $NIO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook_subscription_app",
    "app_id": 23,
    "url": "https://your-host.example/hooks/narrative",
    "name": "reddit-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 23, "name": "reddit-deliveries",
#    "secret": "<WEBHOOK_SECRET>", "status": "active", ...}
```

Keep the `secret` to verify each delivery. The connector sends these events:

| Event | Sent when |
| - | - |
| `audience.delivery.completed` | A delivery to a Custom Audience finishes |
| `audience.delivery.failed` | A delivery to a Custom Audience fails |
| `audience.expiry.completed` | Members leave an audience because their [`ttl_days`](/guides/connectors/reddit/audiences-api#remove-members-after-a-number-of-days) period ran out |
| `audience.expiry.failed` | Removing members whose `ttl_days` period ran out fails |

Read a subscription with `GET /webhooks/{webhook_id}`. To stop the notifications, delete the subscription with `DELETE /webhooks/{webhook_id}`. See [App subscription](/reference/webhooks/event-reference.md#app-subscription) for the subscription fields and [Verifying deliveries](/reference/webhooks/event-reference.md#verifying-deliveries) for checking the secret.

***

## Related content

> **[Reddit Connector](/reference/connectors/reddit.md)**
>
> Supported identifiers, profiles, and invites

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

> **[Webhook Event Reference](/reference/webhooks/event-reference.md)**
>
> Subscription fields, delivery payloads, and verification

> **[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.