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

# Chevre API Authentication — API Keys, Scopes, and Rotation

> Learn how to generate API keys, set scopes, authenticate requests, rotate keys, and handle authentication errors in the Chevre API.

Every Chevre API request must be authenticated using an API key. API keys are workspace-scoped and must be passed in the `Authorization` header as a Bearer token. Without a valid key, all requests return a `401 Unauthorized` response.

## Generating an API Key

<Steps>
  <Step title="Open API Keys settings">
    Navigate to **Settings → API Keys** in your Chevre dashboard.
  </Step>

  <Step title="Create a new key">
    Click **New Key**, enter a descriptive name (e.g., `production-integration`), and choose the appropriate scope for your use case.
  </Step>

  <Step title="Copy and store the key">
    Copy the key immediately and store it somewhere secure — a secrets manager or environment variable. Chevre will never display the full key again after you close this dialog.
  </Step>
</Steps>

<Warning>
  Your API key is shown **only once** at the moment of creation. If you lose it, you must rotate or revoke the key and generate a new one. There is no way to retrieve the original value.
</Warning>

## Authenticating Requests

Pass your API key as a Bearer token in the `Authorization` header of every request:

```
Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx
```

The following examples show authenticated requests across common HTTP clients:

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.chevre.io/v1/workspaces \
    -H "Authorization: Bearer ck_live_xxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json"
  ```

  ```javascript JavaScript (fetch) theme={null}
  const response = await fetch('https://api.chevre.io/v1/workspaces', {
    method: 'GET',
    headers: {
      'Authorization': 'Bearer ck_live_xxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python (requests) theme={null}
  import requests

  headers = {
      "Authorization": "Bearer ck_live_xxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
  }

  response = requests.get("https://api.chevre.io/v1/workspaces", headers=headers)
  data = response.json()
  print(data)
  ```

  ```javascript Node.js (axios) theme={null}
  const axios = require('axios');

  const response = await axios.get('https://api.chevre.io/v1/workspaces', {
    headers: {
      'Authorization': 'Bearer ck_live_xxxxxxxxxxxxxxxxxxxx',
      'Content-Type': 'application/json',
    },
  });

  console.log(response.data);
  ```
</CodeGroup>

## API Key Scopes

When you create a key, you assign it a scope that controls what actions it can perform. Always use the most restrictive scope that your integration actually needs.

| Scope   | Access                                                                             |
| ------- | ---------------------------------------------------------------------------------- |
| `read`  | Read-only access to all resources in the workspace.                                |
| `write` | Create and update resources, in addition to all `read` permissions.                |
| `admin` | Full access including member management, billing settings, and key administration. |

## Rotating a Key

Rotate a key to issue a new secret value while keeping the same key name and scope. Use this as part of a regular security rotation policy or if you suspect a key has been exposed.

Navigate to **Settings → API Keys → (key name) → Rotate**.

<Warning>
  The old key stops working **immediately** when you rotate it. Update all services and environment variables with the new key before rotating to avoid downtime.
</Warning>

## Revoking a Key

To permanently delete a key and prevent any further use, navigate to **Settings → API Keys → (key name) → Revoke**. Revocation is immediate and cannot be undone.

## Authentication Errors

| Status | Code                 | Cause                                                                   |
| ------ | -------------------- | ----------------------------------------------------------------------- |
| `401`  | `unauthorized`       | The `Authorization` header is missing or the token is malformed.        |
| `401`  | `invalid_api_key`    | The key was not recognized — it may have been revoked or never existed. |
| `403`  | `insufficient_scope` | The key was valid but its scope does not permit the requested action.   |

<Tip>
  New to Chevre? See the [Quick Setup Guide](/getting-started/authentication) for a step-by-step walkthrough of creating your first API key and making your first authenticated request.
</Tip>