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

# API Keys

> Create and manage API keys to authenticate with the Coval API

API keys are used to authenticate requests to the Coval REST API and CLI. You can create multiple keys per organization, each with its own permissions and lifecycle.

## Creating an API Key

<Steps>
  <Step title="Open Settings">
    Navigate to **Settings** in the Coval dashboard sidebar, then select the **API Keys** tab.
  </Step>

  <Step title="Click Create Key">
    Click the **Create Key** button in the top right corner.
  </Step>

  <Step title="Configure your key">
    Fill in the following fields:

    | Field           | Required | Description                                                                  |
    | --------------- | -------- | ---------------------------------------------------------------------------- |
    | **Name**        | Yes      | A descriptive name for the key (e.g., "CI/CD Pipeline", "Local Development") |
    | **Description** | No       | Optional notes about the key's purpose                                       |
    | **Key Type**    | Yes      | **Service** for automated systems, **User** for individual access            |
    | **Permissions** | Yes      | **Full Access** or scoped to specific resources                              |
  </Step>

  <Step title="Save your key">
    Click **Create Key**. Your API key will be displayed once.

    <Warning>
      Copy the key immediately. You will not be able to view the full key again after closing the dialog.
    </Warning>
  </Step>
</Steps>

## Using Your API Key

Include the key in the `X-API-Key` header with every request:

```bash theme={null}
curl https://api.coval.dev/v1/agents \
  -H "X-API-Key: your_api_key"
```

Or set it as an environment variable for the CLI:

```bash theme={null}
export COVAL_API_KEY=your_api_key
coval agents list
```

## Permissions

By default, keys are created with **Full Access** to all resources. You can restrict a key to specific scopes using the permissions picker.

Available permission scopes:

| Resource       | Scopes                                                                 |
| -------------- | ---------------------------------------------------------------------- |
| Runs           | `runs:read`, `runs:write`                                              |
| Agents         | `agents:read`, `agents:write`                                          |
| Conversations  | `conversations:read`, `conversations:submit`, `conversations:delete`   |
| Metrics        | `metrics:read`, `metrics:write`, `metrics:delete`                      |
| Test Sets      | `test-sets:read`, `test-sets:write`                                    |
| Test Cases     | `test-cases:read`, `test-cases:write`                                  |
| Personas       | `personas:read`, `personas:write`, `personas:delete`                   |
| Simulations    | `simulations:read`, `simulations:write`                                |
| Traces         | `traces:read`, `traces:write`                                          |
| Dashboards     | `dashboards:read`, `dashboards:write`, `dashboards:delete`             |
| Scheduled Runs | `scheduled-runs:read`, `scheduled-runs:write`, `scheduled-runs:delete` |
| Run Templates  | `run-templates:read`, `run-templates:write`, `run-templates:delete`    |
| API Keys       | `api-keys:read`, `api-keys:write`, `api-keys:delete`                   |

<Tip>
  Use the **preset buttons** to quickly configure common permission sets like **Read Only**, **Run Evaluations**, or **Upload Conversations**.
</Tip>

## Managing Key Status

Each key has a lifecycle status that controls whether it can authenticate requests.

| Status        | Description                                      |
| ------------- | ------------------------------------------------ |
| **Active**    | The key is working and can authenticate requests |
| **Suspended** | Temporarily disabled. Can be reactivated         |
| **Revoked**   | Permanently disabled. Cannot be reactivated      |

### Suspending a Key

To temporarily disable a key, click the **actions menu** (three dots) on the key row and select **Suspend**. Suspended keys can be reactivated at any time.

### Revoking a Key

To permanently disable a key, select **Revoke** from the actions menu. You must provide a reason. Revoked keys cannot be reactivated.

<Warning>
  Revoking a key is permanent. Any systems using the key will immediately lose access.
</Warning>

### Deleting a Key

To remove a key entirely, select **Delete** from the actions menu. This permanently removes the key record from your organization.

## Filtering Keys

Use the status tabs above the table to filter keys by their current status:

* **All** — Show all keys
* **Active** — Only active keys
* **Suspended** — Only suspended keys
* **Revoked** — Only revoked keys

## Best Practices

<CardGroup cols={2}>
  <Card title="Use scoped permissions" icon="shield">
    Avoid full access keys in production. Scope each key to only the permissions it needs.
  </Card>

  <Card title="Rotate keys regularly" icon="arrows-rotate">
    Create new keys and revoke old ones periodically, especially for production systems.
  </Card>

  <Card title="Use descriptive names" icon="tag">
    Name keys after their purpose (e.g., "GitHub Actions CI", "Staging Environment") so you can identify them later.
  </Card>

  <Card title="Revoke unused keys" icon="ban">
    Promptly revoke keys that are no longer in use to minimize your attack surface.
  </Card>
</CardGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="API Reference" icon="square-terminal" href="/api-reference/v1/introduction">
    Explore the full API documentation
  </Card>

  <Card title="CLI Installation" icon="terminal" href="/cli/installation">
    Install the Coval CLI and authenticate with your key
  </Card>

  <Card title="CLI API Keys Commands" icon="key" href="/cli/api-keys">
    Manage API keys programmatically from the command line
  </Card>

  <Card title="GitHub Actions" icon="code-branch" href="/getting-started/github-actions-tutorial">
    Use API keys in your CI/CD pipeline
  </Card>
</CardGroup>