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

# API Keys

> Create Bearer tokens for programmatic access to the NeuronSearchLab console API.

API keys provide a simple way to authenticate programmatic requests against the NeuronSearchLab Platform API. Unlike [SDK Credentials](/authentication), which issue OAuth access tokens for the Core API, API keys are Bearer tokens for server-side console automation.

## When to use API keys vs SDK credentials

|                     | API Keys                                                 | SDK Credentials                                           |
| ------------------- | -------------------------------------------------------- | --------------------------------------------------------- |
| **Auth method**     | Bearer token (`nsl_...`)                                 | OAuth 2.0 client credentials                              |
| **Endpoint**        | [Platform API](/api-reference/platform-api/introduction) | [Core API](/api-reference/introduction)                   |
| **Rerank controls** | Read and update configuration                            | Used only when serving code calls the Core API            |
| **Use case**        | Internal tools and console automation                    | Production recommendation, event, and catalog integration |

## Create an API key

<Steps>
  <Step title="Open API Keys">
    Navigate to **Console > API Keys**.
  </Step>

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

  <Step title="Name the key">
    Enter a descriptive name, for example "Staging Backend" or "Internal Dashboard".
  </Step>

  <Step title="Tag the environment">
    Select an environment tag for organisational purposes.
  </Step>

  <Step title="Choose scopes">
    Choose which scopes the key can access: `recommendations`, `events`, or `items`.
  </Step>

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

The full key is displayed once. Copy it immediately and store it securely.

## Authenticate requests

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

```bash theme={null}
curl "https://console.neuronsearchlab.com/api/rerank-controls?contextId=101" \
  -H "Authorization: Bearer nsl_abc12345_..."
```

For recommendation serving, use SDK Credentials with the Core API instead of API keys.

## Key format

API keys follow the format `nsl_<prefix>_<token>`:

* `nsl_` — fixed prefix identifying a NeuronSearchLab key.
* `<prefix>` — 8-character identifier shown in the console for easy recognition.
* `<token>` — the full random token. Only the SHA-256 hash is stored server-side.

## Scopes

Each key is restricted to specific API scopes:

| Scope             | Grants access to                                                                                                                |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `recommendations` | Reserved for recommendation-related internal tools. Current documented Platform API routes use `admin` unless stated otherwise. |
| `events`          | Event configuration routes that explicitly allow the `events` scope.                                                            |
| `items`           | Reserved for catalog automation routes that explicitly allow the `items` scope.                                                 |
| `admin`           | Full Platform API access.                                                                                                       |

If a key lacks the required scope, the Platform API returns `403 Forbidden`.

## Revoke a key

<Steps>
  <Step title="Open API Keys">
    Navigate to **Console > API Keys**.
  </Step>

  <Step title="Revoke the key">
    Click **Revoke** on the key you want to deactivate.
  </Step>
</Steps>

Revocation is immediate and permanent. Create a new key if you need to restore access.

## Security practices

* **One key per service or environment.** Avoid sharing keys across applications.
* **Tag keys with the correct environment** to make auditing easier.
* **Rotate keys periodically.** Create a new key, deploy it, then revoke the old one.
* **Never expose keys client-side.** API keys are for server-to-server use only.