Skip to main content
API keys authenticate requests to the Narrative API. You can use them when calling APIs directly or when configuring other systems to make requests on your behalf.

​
Viewing your API keys

Navigate to Settings > API Keys to view your existing API keys. You’ll see a list of your keys along with their expiration dates and assigned permissions.

​
API key permissions

Each API key permission is a combination of an access level (Read or Write) and a resource (a functional area of the platform like Datasets, Connections, or Jobs). A key can hold multiple permissions, and they are additive—each one grants additional capabilities.
For a deeper explanation of how permissions work, see API Key Permissions. For a complete list of all resources and access levels, see the Permissions Reference.
Use minimum permissionsWhen creating an API key, grant only the permissions necessary for its intended function. This security best practice helps protect your data and account from unauthorized access.

​
Choosing permissions for common use cases

Use the table below to determine which permissions to assign based on what your key needs to do.
Use caseRecommended permissions
Read-only analyticsRead on Datasets, Queries, and Subscriptions
Data ingestionWrite on Datasets and DataStreams
Workflow automationRead and Write on Workflows and Jobs
Connector deliveryRead and Write on Connections and Destinations
SDK developmentRead and Write on the resources your application uses (see SDK Authentication)

​
API key expiration

API keys can have an expiration date, after which they’re no longer valid.
Set expiration dates and rotate keys regularlyWe highly recommend setting an expiration date for all API keys and rotating them on a regular schedule.

​
Creating a new API key

1

Open the API Keys page

Navigate to Settings > API Keys.
2

Create the key

Click New API Key.
3

Configure the key

Enter a name for the key, select the permissions you want to grant, and set an expiration date. See common use cases for guidance on which permissions to select.
4

Save your key

Copy and securely store the API key. You won’t be able to view the full key again after this step.

​
Revoking an API key

To revoke an API key:
  1. Navigate to Settings > API Keys.
  2. Click the … menu next to the key you want to revoke.
  3. Select Delete.
The key is immediately revoked and can no longer be used to make requests to the Narrative API.

​
Related content

API Key Permissions

Understand how scoped permissions protect your resources

Permissions Reference

All available permission resources and access levels

SDK Authentication

Configure API key authentication for the TypeScript SDK

Security Model

How Narrative protects your data

​
Responding to a security incident

If you suspect your API keys have been compromised:
  1. Revoke all affected API keys immediately using the steps above.
  2. Create new API keys with appropriate permissions.
  3. Report the incident to Narrative security so we can help you investigate and take appropriate action.