Skip to main content
POST
/
v1
/
api-keys
curl --request POST \
  --url https://api.coval.dev/v1/api-keys \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{}'
{
  "api_key": {
    "id": "01HX2ABC3DEF4GHI5JKL6MNO7P",
    "organization_id": "caf26438",
    "api_key": "coval_sk_prod_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6",
    "key_type": "SERVICE",
    "status": "ACTIVE",
    "name": "Production Service Key",
    "description": "Primary key for production backend service authentication",
    "permissions": [],
    "create_time": "2025-10-14T12:00:00Z",
    "update_time": null,
    "last_used_at": null
  }
}

Authorizations

​
X-API-Key
string
header
required

API key for authentication

Body

application/json
​
name
string | null

Human-readable name for the API key

Maximum string length: 200
Example:

"Production Service Key"

​
description
string | null

Detailed description of the API key purpose

Maximum string length: 2000
Example:

"Primary key for production backend service authentication"

​
key_type
enum<string>
default:SERVICE

Type of API key.

  • SERVICE: Machine-to-machine authentication for backend services and integrations
  • USER: User-scoped key tied to individual user actions
Available options:
SERVICE,
USER
Example:

"SERVICE"

​
permissions
enum<string>[]

Permission scopes to grant. Empty array (default) grants full access.

Permission scope. Format: resource:action, resource:*, or * for full access. Empty array [] grants full access.

Available options:
*,
runs:read,
runs:write,
runs:*,
agents:read,
agents:write,
agents:*,
conversations:read,
conversations:submit,
conversations:*,
metrics:read,
metrics:*,
test-sets:read,
test-sets:write,
test-sets:*,
test-cases:read,
test-cases:write,
test-cases:*,
personas:read,
personas:write,
personas:delete,
personas:*,
simulations:read,
simulations:write,
simulations:*,
traces:read,
traces:*,
dashboards:read,
dashboards:write,
dashboards:delete,
dashboards:*,
api-keys:read,
api-keys:write,
api-keys:delete,
api-keys:*,
scheduled-runs:read,
scheduled-runs:write,
scheduled-runs:delete,
scheduled-runs:*,
run-templates:read,
run-templates:write,
run-templates:delete,
run-templates:*
Example:
[]

Response

API key created successfully

​
api_key
object
required

API key resource with full key value. Only returned during creation.