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

> Prerequisites and API access every TikTok Connector API guide needs

The TikTok Connector API lets an unattended integration deliver audiences to TikTok Ads Manager and send offline conversion events to TikTok Events Manager. A person signs in once to create an API key and once to connect a profile to TikTok, 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 TikTok API guide. The guides are listed under **Guides** on the [TikTok Connector](/reference/connectors/tiktok.md#guides) and [TikTok Conversions API Connector](/reference/connectors/tiktok-conversions-api.md#guides) reference pages.

## Prerequisites

What you need depends on the guide you follow:

| Prerequisite | Audiences | Conversion events |
| - | :-: | :-: |
| [API key](#api-key) | ✓ | ✓ |
| [TikTok Connector installed](#tiktok-connector-installed) | ✓ | ✓ |
| [A profile connected to TikTok](#a-profile-connected-to-tiktok) | ✓ | ✓ |
| [An advertiser on the profile](#list-your-advertisers) | ✓ | |
| [An Offline Event Set ID](#an-offline-event-set-id) | | ✓ |

### API key

Create the key under **Settings → API Keys** with read and write on `datasets` and `connections`, write on `uploads`, and 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.

### TikTok Connector installed

The TikTok Connector is app `19`. Find your installation of it:

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

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

### A profile connected to TikTok

A connector profile holds the TikTok for Business authorization that every delivery uses. The profile also decides which TikTok advertisers you can deliver to. Create the profile once, in the Narrative UI:

**1. Open the connector**

In Narrative, go to **Installed Apps** and select **TikTok Connector**.

**2. Create a profile**

In the **Profiles** tab, create a profile and give it a name.

**3. Connect to TikTok**

Choose **Connect**, sign in to TikTok for Business as someone with access to the advertisers you want to deliver to, select those advertisers, and approve the access request.

You can also start the sign-in from the API, once you have an [installation token](#get-an-installation-token). Ask the connector for the profile's TikTok authorization URL:

```bash theme={null}
curl -s -X POST https://tiktok.narrativeconnectors.com/profiles/{profile_id}/connect \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"url": "https://business-api.tiktok.com/portal/auth?...",
#    "expires_at": "2025-01-02T12:00:00Z"}
```

Open the `url` in a browser before `expires_at`, which is 24 hours after the request. Sign in to TikTok for Business, select the advertisers, and approve. TikTok then sends the browser to the TikTok connector, which saves the authorization and returns an empty page. To confirm the profile is connected, [list its advertisers](#list-your-advertisers).

You connect a profile once. The profile can then deliver to every advertiser you selected, from any number of connections.

### An Offline Event Set ID

Conversion events go to an Offline Event Set in TikTok Events Manager. Create one there for the advertiser that should receive the events, and copy its ID. Each event row you upload carries this ID.

## 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 |
| TikTok connector | `https://tiktok.narrativeconnectors.com` | An installation token | Profiles, advertisers, audiences, settings checks |

### Get an installation token

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

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

### Find your profile

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

```bash theme={null}
curl -s https://tiktok.narrativeconnectors.com/profiles/{profile_id} \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"id": "<PROFILE_ID>", "created_at": "2025-01-01T12:00:00Z",
#    "company_id": 1234, "name": "Example Brand", "status": "enabled",
#    "updated_at": "2025-01-01T12:00:00Z"}
```

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

### List your advertisers

Advertisers are the TikTok advertiser accounts the profile can deliver to, which are the ones selected when the profile was connected:

```bash theme={null}
curl -s https://tiktok.narrativeconnectors.com/profiles/{profile_id}/advertisers \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<ADVERTISER_ID>", "name": "Example Advertiser"},
#                {"id": "<ADVERTISER_ID>", "name": "Example Outlet Advertiser"}]}
```

Record the `id` of the advertiser you deliver to.

### List the audiences in an advertiser

```bash theme={null}
curl -s "https://tiktok.narrativeconnectors.com/profiles/{profile_id}/advertisers/{advertiser_id}/audiences?page=1&page_size=100" \
  -H "Authorization: Bearer $INSTALLATION_TOKEN"
# → {"records": [{"id": "<AUDIENCE_ID>", "name": "Spring Buyers"},
#                {"id": "<AUDIENCE_ID>", "name": "Newsletter Subscribers"}],
#    "page_info": {"page": 1, "page_size": 100, "total_number": 2, "total_page": 1}}
```

Each record is an audience in that advertiser, with its TikTok audience ID and name. When `total_page` is more than 1, request the next `page`. The [audience delivery guide](/guides/connectors/tiktok/audiences-api.md) uses this list to find audience IDs.

## Connection settings

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

## Delivery notifications

The TikTok Connector reports each delivery as an app webhook event. Subscribe a webhook to app `19` 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": 19,
    "url": "https://your-host.example/hooks/narrative",
    "name": "tiktok-deliveries"
  }'
# → {"id": "<WEBHOOK_ID>", "app_id": 19, "name": "tiktok-deliveries",
#    "secret": "<WEBHOOK_SECRET>", "status": "active",
#    "url": "https://your-host.example/hooks/narrative", ...}
```

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

| Event | Sent when |
| - | - |
| `audience.delivery.completed` | A delivery to a TikTok audience finishes |
| `audience.delivery.failed` | A delivery to a TikTok audience fails |
| `audience.delivery.quota_exceeded` | A delivery to a TikTok audience stops at TikTok's daily quota. The connector sends this event instead of `audience.delivery.failed` |
| `conversion.delivery.completed` | A delivery of conversion events finishes |
| `conversion.delivery.failed` | A delivery of conversion events fails |
| `conversion.delivery.quota_exceeded` | A delivery of conversion events stops at TikTok's daily quota. The connector sends this event instead of `conversion.delivery.failed` |

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

> **[TikTok Connector](/reference/connectors/tiktok.md)**
>
> Supported identifiers and connector setup

> **[TikTok Conversions API Connector](/reference/connectors/tiktok-conversions-api.md)**
>
> Conversion event fields, event names, and identifier matching

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