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

# Authentication: API Keys and Secure Access in Chevre

> Learn how to generate Chevre API keys, authenticate REST API requests, choose the right key scope, and rotate or revoke credentials safely.

Chevre uses API keys to authenticate requests to the Chevre REST API. Every request you make must include your API key in the `Authorization` header as a Bearer token. Without a valid key, the API returns a `401 Unauthorized` error.

## Generating an API Key

Create a new API key from your Chevre workspace settings:

<Steps>
  <Step title="Open API Key Settings">
    From your workspace dashboard, click **Settings** in the left sidebar, then select **API Keys**.
  </Step>

  <Step title="Create a New Key">
    Click **+ New Key** in the top-right corner of the API Keys page.
  </Step>

  <Step title="Name and Scope Your Key">
    Enter a descriptive name for the key (for example, `Production Integration` or `CI Pipeline`) and select the appropriate **scope** for what this key needs to do. See [API Key Scopes](#api-key-scopes) below for details.
  </Step>

  <Step title="Copy and Store the Key">
    Click **Generate Key**. Chevre displays the full API key **once** — copy it immediately and store it in a secure location such as a password manager or secrets vault. You won't be able to view the key again after closing this dialog.
  </Step>
</Steps>

<Warning>
  Treat your API key like a password. Never commit it to source control, paste it into public forums, or share it in plain text. If a key is ever exposed, revoke it immediately and generate a new one.
</Warning>

## Making Authenticated Requests

Pass your API key in the `Authorization` header using the `Bearer` scheme on every API request.

```bash theme={null}
curl https://api.chevre.io/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY"
```

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

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

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

  response = requests.get(
      "https://api.chevre.io/v1/workspaces",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
  )

  data = response.json()
  print(data)
  ```
</CodeGroup>

Replace `YOUR_API_KEY` with the key you copied from Settings. Keep it out of your source code — use environment variables instead:

<CodeGroup>
  ```bash Shell theme={null}
  export CHEVRE_API_KEY="your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.chevre.io/v1/workspaces", {
    headers: {
      "Authorization": `Bearer ${process.env.CHEVRE_API_KEY}`,
    },
  });
  ```
</CodeGroup>

## API Key Scopes

When generating a key, choose the scope that matches the minimum access your integration needs. Following the principle of least privilege reduces risk if a key is ever compromised.

| Scope   | What It Allows                                                                                                                                                                   |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `read`  | Read-only access to all resources in the workspace (workflows, projects, run logs, members). Cannot create, update, or delete anything.                                          |
| `write` | All `read` permissions, plus the ability to create, update, and trigger workflows, manage projects, and write to other resources. Cannot manage billing or delete the workspace. |
| `admin` | Full access, including workspace settings, member management, billing, API key management, and all `write` permissions. Use with caution and restrict to trusted services only.  |

## Rotating and Revoking Keys

Rotate keys regularly or immediately when you suspect exposure:

**To rotate a key:**

1. Generate a new key with the same scope from **Settings → API Keys → + New Key**.
2. Update your integration or environment variable to use the new key.
3. Revoke the old key once you've confirmed the new one is working.

**To revoke a key:**

1. Go to **Settings → API Keys**.
2. Find the key you want to remove and click the **⋯** menu to its right.
3. Select **Revoke Key** and confirm. Revocation is immediate — any request using the revoked key will receive a `401` response.

<Warning>
  Revoking a key is permanent and cannot be undone. Make sure all services using the key have been updated before revoking it.
</Warning>

## Error Responses

If authentication fails, the API returns a standard error response. The two most common authentication-related errors are:

| HTTP Status        | Error Code           | Cause                                                                                             | Resolution                                                                                     |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `401 Unauthorized` | `INVALID_API_KEY`    | The `Authorization` header is missing, malformed, or the key has been revoked.                    | Verify the header format is `Bearer YOUR_API_KEY` and that the key is active in Settings.      |
| `403 Forbidden`    | `INSUFFICIENT_SCOPE` | The API key exists and is valid, but it doesn't have the scope required for the requested action. | Generate a new key with the appropriate scope, or use an existing key with higher permissions. |

All error responses follow this JSON structure:

```json theme={null}
{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key provided is missing or invalid.",
    "status": 401
  }
}
```

<Tip>
  For the full API authentication reference — including OAuth 2.0 token flows for user-delegated access — see the [API Authentication Reference](/api-reference/authentication).
</Tip>