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:
FieldRequiredDescription
NameYesA descriptive name for the key (e.g., “CI/CD Pipeline”, “Local Development”)
DescriptionNoOptional notes about the key’s purpose
Key TypeYesService for automated systems, User for individual access
PermissionsYesFull Access or scoped to specific resources
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: 
curl https://api.coval.dev/v1/agents \
  -H "X-API-Key: your_api_key"
Or set it as an environment variable for the CLI: 
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:
ResourceScopes
Runsruns:read, runs:write
Agentsagents:read, agents:write
Conversationsconversations:read, conversations:submit, conversations:delete
Metricsmetrics:read, metrics:write, metrics:delete
Test Setstest-sets:read, test-sets:write
Test Casestest-cases:read, test-cases:write
Personaspersonas:read, personas:write, personas:delete
Simulationssimulations:read, simulations:write
Tracestraces:read, traces:write
Dashboardsdashboards:read, dashboards:write, dashboards:delete
Scheduled Runsscheduled-runs:read, scheduled-runs:write, scheduled-runs:delete
Run Templatesrun-templates:read, run-templates:write, run-templates:delete
API Keysapi-keys:read, api-keys:write, api-keys:delete
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.
StatusDescription
ActiveThe key is working and can authenticate requests
SuspendedTemporarily disabled. Can be reactivated
RevokedPermanently 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.
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