Skip to main content
API key permissions control what each key can do within the Narrative platform. By assigning specific permissions to each key, you limit its capabilities to only what’s needed—reducing risk and making your integrations easier to reason about.

​
Why scope API key permissions

Principle of least privilege. A key that can only read datasets cannot accidentally modify or delete them. Scoping permissions limits the blast radius of a compromised or misconfigured key to only the resources it was granted access to. Operational clarity. When each key has a clear, narrow purpose, it’s easy to understand what a key is for just by looking at its permissions. A key with Read Datasets and Read Queries is obviously for analytics, not for data ingestion or workflow management. Auditability. Scoped keys make audit logs more meaningful. When an action occurs, the key’s permissions tell you not just who performed it, but what category of operation was intended—helping you quickly identify unexpected behavior.

​
How permissions work

Every API key permission is a combination of two things:
  • Access level — What the key can do: Read (view and list resources) or Write (create, update, and delete resources)
  • Resource — Which functional area of the platform the permission applies to, such as Datasets, Connections, or Jobs
For example, a key with Read Datasets permission can view dataset metadata, samples, and statistics, but cannot create new datasets or modify existing ones. Adding Write Datasets would grant the ability to create, update, and delete datasets as well.

​
How permissions compose

API keys can hold multiple permissions. Permissions are additive—each permission grants additional capabilities, and there are no deny rules. A key’s effective access is the union of all its assigned permissions. If a key attempts an operation that requires a permission it doesn’t have, the API returns a 401 Unauthorized response. This applies even if the key has other permissions—each resource and access level is checked independently.

​
Choosing the right scope

When deciding which permissions to assign to a key, consider:
  • Think about the key’s purpose. What specific tasks will this key perform? Start with the minimum permissions needed for those tasks and add more only if required.
  • Separate concerns across keys. Use different keys for different systems or workflows. A key for your analytics dashboard shouldn’t also have permissions to manage workflows or modify datasets.
  • Review permissions periodically. As your integration evolves, the permissions a key needs may change. Audit your keys regularly and remove permissions that are no longer necessary.
For a complete list of all available resources and their access levels, see the Permissions Reference.

​
Related content

Permissions Reference

All API key permission resources and their available access levels

API Keys

Create and manage API keys with scoped permissions

Security Model

How Narrative protects your data through architecture and access controls

SDK Authentication

Configure API key authentication for the TypeScript SDK