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.

​
API key expiration

Every API key expires — expiration is not optional. When you create a key you choose the date, which must be between 1 and 365 days out. Omit it and you get the maximum, 365 days. Expiry is stored with day granularity, so the date you ask for is rounded down to a whole number of days from creation: ask for 36 hours and you get 24. A date less than a full day out rounds down to zero days and is rejected. You can push an existing key’s expiry out by updating the key, subject to the same 365-day ceiling measured from the time of the update. Because no key can outlive a year, plan for annual rotation.
Create integration keys from a service accountFor a key that authenticates an unattended integration, create it from a shared service account rather than a personal login. The integration then survives staff changes, and the annual rotation has an owner who isn’t a single person.

​
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.