> ## Documentation Index
> Fetch the complete documentation index at: https://developers.scrunch.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Provision an API key

> Create, scope, and rotate Scrunch API keys at the organization level to authenticate Query, Responses, Configuration, and Agent Traffic requests.

Scrunch API keys authenticate your requests and define which brands and operations your integration can access. Only organization admins can create or manage API keys.

<Note>
  API keys are shown **once** at creation time. Be sure to copy and store them securely.
</Note>

## Plan Requirements

API key creation is available on the **Agency** and **Enterprise** plans. If your organization is on a different plan, the **New API Key** button is disabled and you'll see an upgrade prompt when attempting to create one.

If you need API access on another plan, contact [support@scrunchai.com](mailto:support@scrunchai.com) to discuss an override for your organization.

<Note>
  Attempts to call `POST /organizations/{organization_id}/api-keys` without the required plan capability return HTTP `402 Payment Required`.
</Note>

## Where API Keys Live

API keys are managed at the organization level.

You can find them by clicking your **organization name** in the top-left corner of the Scrunch dashboard, then selecting **API Keys**.

This area is available only to organization admins and is also where you manage brands and archival operations.

## Create an API Key

Complete these steps in your Scrunch UI to provision an API Key (`$SCRUNCH_API_TOKEN`).

<Steps>
  <Step title="Open the organization menu">
    Click your **organization name** in the top-left corner of the Scrunch dashboard.

    <Frame>
      <img src="https://mintcdn.com/scrunchai/jjpfPER2d5Ppa7xu/images/org_settings.png?fit=max&auto=format&n=jjpfPER2d5Ppa7xu&q=85&s=2bd8a5534c8347244122b1b564b7a994" alt="Organization selector showing API access" width="942" height="360" data-path="images/org_settings.png" />
    </Frame>
  </Step>

  <Step title="Open API Keys">
    Select **API Keys** from the organization menu.

    <Frame>
      <img src="https://mintcdn.com/scrunchai/-UAm6mPL0fGNQQb9/images/Screenshot2026-03-05at2.07.51PM.png?fit=max&auto=format&n=-UAm6mPL0fGNQQb9&q=85&s=94a16d4455ea35058bf4358faaa81ddd" alt="Screenshot 2026 03 05 At 2 07 51 PM" width="734" height="496" data-path="images/Screenshot2026-03-05at2.07.51PM.png" />
    </Frame>
  </Step>

  <Step title="Create a new API key">
    Click **+ New API Key**.
  </Step>

  <Step title="Choose the key scope">
    Scrunch supports several operational scopes:

    * Query (retrieve analytics and metrics)
    * Configure (update brand configuration, prompts, etc.)
    * Create Brand (programmatically create brands)

    Choose the minimal scope required for your integration.

    <Frame>
      <img src="https://mintcdn.com/scrunchai/-UAm6mPL0fGNQQb9/images/Screenshot2026-03-05at2.08.43PM.png?fit=max&auto=format&n=-UAm6mPL0fGNQQb9&q=85&s=c805071a7f38ebadbd28b4310dfe6d7b" alt="Screenshot 2026 03 05 At 2 08 43 PM" width="1316" height="862" data-path="images/Screenshot2026-03-05at2.08.43PM.png" />
    </Frame>
  </Step>

  <Step title="Select brand access">
    You may scope the key to:

    * **Specific brand(s)** (recommended for client-facing reporting)
    * **All brands** (recommended for internal tooling or ETL pipelines)
  </Step>

  <Step title="Create and copy the key">
    Scrunch displays the key **once**. Copy it immediately and store it securely.
  </Step>
</Steps>

## Use Your API Key

Include your key as a Bearer token in the `Authorization` header.

```bash theme={null}
export SCRUNCH_API_TOKEN="your-key"

curl -H "Authorization: Bearer $SCRUNCH_API_TOKEN" \
  https://api.scrunchai.com/v1/brands
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Use brand-scoped keys" icon="lock">
    Limit access when integrating with client-facing dashboards or BI tools.
  </Card>

  <Card title="Reserve org-wide keys" icon="shield-check">
    Use for internal workflows only (e.g., multi-brand ETL, automation).
  </Card>

  <Card title="Rotate keys periodically" icon="rotate">
    Especially important for deployments or CI environments.
  </Card>

  <Card title="Archive inactive clients" icon="archive">
    Keeps your organization clean and prevents accidental access.
  </Card>
</CardGroup>

## Troubleshooting

<warning>
  If you don't see the **API Keys** tab, you are likely not an organization admin. Contact your Scrunch admin or [support@scrunchai.com](mailto:support@scrunchai.com).
</warning>

If a key cannot access a brand:

* Verify the key's scope includes that brand
* Check that the brand has not been archived