Skip to main content
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

1

Open Settings

Navigate to Settings in the Coval dashboard sidebar, then select the API Keys tab.
2

Click Create Key

Click the Create Key button in the top right corner.
3

Configure your key

Fill in the following fields:
4

Save your key

Click Create Key. Your API key will be displayed once.
Copy the key immediately. You will not be able to view the full key again after closing the dialog.

​
Using Your API Key

Include the key in the X-API-Key header with every request:
Or set it as an environment variable for the CLI:

​
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:
Use the preset buttons to quickly configure common permission sets like Read Only, Run Evaluations, or Upload Conversations.

​
Managing Key Status

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

​
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.
Revoking a key is permanent. Any systems using the key will immediately lose access.

​
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

Use scoped permissions

Avoid full access keys in production. Scope each key to only the permissions it needs.

Rotate keys regularly

Create new keys and revoke old ones periodically, especially for production systems.

Use descriptive names

Name keys after their purpose (e.g., “GitHub Actions CI”, “Staging Environment”) so you can identify them later.

Revoke unused keys

Promptly revoke keys that are no longer in use to minimize your attack surface.

​
Next Steps

API Reference

Explore the full API documentation

CLI Installation

Install the Coval CLI and authenticate with your key

CLI API Keys Commands

Manage API keys programmatically from the command line

GitHub Actions

Use API keys in your CI/CD pipeline