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

# API Keys

> Create, manage, and secure API keys for authenticating requests to the Narrative API

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.

<Note>
  For a deeper explanation of how permissions work, see [API Key Permissions](/concepts/security/api-key-permissions). For a complete list of all resources and access levels, see the [Permissions Reference](/reference/security/permissions).
</Note>

<Tip>
  **Use minimum permissions**

  When 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.
</Tip>

### 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 case                | Recommended permissions                                                                                      |
| ----------------------- | ------------------------------------------------------------------------------------------------------------ |
| **Read-only analytics** | Read on Datasets, Queries, and Subscriptions                                                                 |
| **Data ingestion**      | Write on Datasets and DataStreams                                                                            |
| **Workflow automation** | Read and Write on Workflows and Jobs                                                                         |
| **Connector delivery**  | Read and Write on Connections and Destinations                                                               |
| **SDK development**     | Read and Write on the resources your application uses (see [SDK Authentication](/guides/sdk/authentication)) |

## API key expiration

API keys can have an expiration date, after which they're no longer valid.

<Tip>
  **Set expiration dates and rotate keys regularly**

  We highly recommend setting an expiration date for all API keys and rotating them on a regular schedule.
</Tip>

## Creating a new API key

<Steps>
  <Step title="Open the API Keys page">
    Navigate to **Settings > API Keys**.
  </Step>

  <Step title="Create the key">
    Click **New API Key**.
  </Step>

  <Step title="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](#choosing-permissions-for-common-use-cases) for guidance on which permissions to select.
  </Step>

  <Step title="Save your key">
    Copy and securely store the API key. You won't be able to view the full key again after this step.
  </Step>
</Steps>

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

<CardGroup cols={2}>
  <Card title="API Key Permissions" icon="lock-keyhole" href="/concepts/security/api-key-permissions">
    Understand how scoped permissions protect your resources
  </Card>

  <Card title="Permissions Reference" icon="table" href="/reference/security/permissions">
    All available permission resources and access levels
  </Card>

  <Card title="SDK Authentication" icon="code" href="/guides/sdk/authentication">
    Configure API key authentication for the TypeScript SDK
  </Card>

  <Card title="Security Model" icon="shield" href="/concepts/architecture/security-model">
    How Narrative protects your data
  </Card>
</CardGroup>

## Responding to a security incident

<Warning>
  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.
</Warning>