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

# API Key Authentication for Beenos Solutions REST API

> Learn how to create, use, scope, and rotate API keys to securely authenticate every request you make to the Beenos Solutions REST API.

The Beenos Solutions API uses API keys to authenticate every request. You must include a valid API key in the `Authorization` header of all requests — the API rejects any request that is missing a key or presents an invalid one with a `401 Unauthorized` response. API keys are tied to your workspace and inherit the permission scope you assign at creation time.

<Warning>
  Never commit API keys to source control. Store them in environment variables or a secrets manager such as AWS Secrets Manager, HashiCorp Vault, or your CI/CD platform's secret store. Rotating an exposed key immediately limits damage — see [Rotating and Revoking Keys](#rotating-and-revoking-keys) below.
</Warning>

## Creating an API Key

Generate a new API key from the Beenos Solutions dashboard. You can create multiple keys with different scopes — for example, one key for your production server and a separate key for local development.

<Steps>
  <Step title="Open the Dashboard">
    Log in to your Beenos Solutions workspace at [app.beenossolutions.com](https://app.beenossolutions.com).
  </Step>

  <Step title="Navigate to Settings">
    Click **Settings** in the left-hand navigation panel.
  </Step>

  <Step title="Open the API Keys section">
    Select the **API Keys** tab within Settings.
  </Step>

  <Step title="Create a new key">
    Click **Create Key**, enter a descriptive name (for example, `Production Server` or `Local Dev`), and choose the appropriate scope for your use case.
  </Step>

  <Step title="Copy your key immediately">
    Your API key is displayed **only once** immediately after creation. Copy it to a secure location right away — you cannot retrieve the full key value again after you close this dialog. If you lose the key, revoke it and generate a new one.
  </Step>
</Steps>

## Using Your API Key

Pass your API key as a Bearer token in the `Authorization` header of every request. Replace `YOUR_API_KEY` with the key you copied from the dashboard.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

Here is a complete example request using `curl`:

```bash theme={null}
curl https://api.beenossolutions.com/v1/agents \
  -H "Authorization: Bearer bns_live_xxxxxxxxxxxx"
```

## API Key Format

Beenos Solutions API keys use a prefix that identifies the environment the key targets. Always verify you are using the correct key type before making requests.

| Prefix      | Environment | Description                                             |
| ----------- | ----------- | ------------------------------------------------------- |
| `bns_live_` | Production  | Targets live data in your production workspace          |
| `bns_test_` | Sandbox     | Targets isolated test data; safe for development and CI |

Using a `bns_test_` key against the production base URL will return a `403 Forbidden` response, and vice versa. Keep your production and sandbox keys strictly separated.

## Key Scopes

When you create an API key, you assign it one of three permission scopes. Choose the most restrictive scope that satisfies your integration's requirements.

| Scope          | Permitted Operations                                  | Typical Use Case                                        |
| -------------- | ----------------------------------------------------- | ------------------------------------------------------- |
| **Read-only**  | `GET` requests only                                   | Dashboards, analytics pipelines, read-only integrations |
| **Read-Write** | All `GET`, `POST`, `PATCH`, and `DELETE` requests     | Application backends, chatbots, content ingestion       |
| **Admin**      | All requests, including workspace settings management | Internal tooling, automated provisioning                |

## Rotating and Revoking Keys

Rotate your API keys periodically as a security best practice, and revoke them immediately if you suspect a key has been exposed.

<Steps>
  <Step title="Create a replacement key">
    Follow the steps in [Creating an API Key](#creating-an-api-key) to generate a new key with the same scope as the key you are replacing.
  </Step>

  <Step title="Update your integration">
    Deploy the new key value to all services and environments that use the old key before you revoke it.
  </Step>

  <Step title="Revoke the old key">
    In the dashboard, go to **Settings → API Keys**, find the old key, and click **Revoke**. Confirm the action in the dialog that appears.
  </Step>
</Steps>

<Warning>
  Revoking a key takes effect immediately and cannot be undone. Any in-flight or subsequent requests that use the revoked key will receive a `401 Unauthorized` response. Make sure you have fully deployed the replacement key before revoking the old one.
</Warning>