Authentication

All Keva API requests require authentication using Bearer tokens. This guide covers creating API keys, authenticating requests, and managing key security.

Authentication Flow

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Your App    │────▶│  Keva API    │────▶│   Response   │
│              │     │              │     │              │
│ Authorization│     │ Validate Key │     │ JSON Data    │
│ Bearer token │     │ Check Scopes │     │ or Error     │
└──────────────┘     └──────────────┘     └──────────────┘

API Key Format

Keva API keys follow a specific format:

keva_live_[64 hex characters]

Example:

keva_live_a1b2c3d4e5f6789012345678901234567890123456789012345678901234abcd

The keva_live_ prefix identifies the key type and helps prevent accidental exposure of other credentials.

Creating an API Key

Important

The full API key is only shown once. Copy and store it securely before closing the dialog.

Using the API Key

Include your API key in the Authorization header with the Bearer prefix:

Scopes

API keys can be restricted to specific operations:

Scope	Permissions
`tickets:read`	List and view tickets and messages
`tickets:write`	Create tickets, add messages, and update status, priority, and assignment

Stored legacy scope values do not imply that a matching public endpoint exists. The current API-key-authenticated /api/v1 surface supports ticket scopes only.

Workspace Selection

Each API key is bound to one workspace when it is created. Requests use that persisted workspace automatically; a request cannot switch workspace with a header. The optional workspace_id query parameter may be used as an explicit assertion and must match the key's bound workspace:

curl "https://app.keva.support/api/v1/tickets?workspace_id=550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer keva_live_your_api_key"

Error Responses

Status	Error	Cause
`401`	Missing or invalid Authorization header	No Bearer token provided
`401`	Invalid API key format	Key doesn't match `keva_live_*` pattern
`401`	Invalid API key	Key not found or revoked
`401`	API key has expired	Key past expiration date
`403`	Insufficient scope	Key lacks required permission

401 Unauthorized

If you receive a 401 error, verify your key is correct, not expired, and not revoked. Check that you're using the Bearer prefix.

Security Best Practices

Never expose keys in client-side code — use server-side requests only
Use a separate key for each integration and revoke access independently
Rotate keys regularly — create new keys and revoke old ones periodically
Monitor usage — check the "Last Used" timestamp in API Key settings
Revoke compromised keys immediately — if a key is exposed, revoke it at once

API Reference

Full endpoint documentation

API Key Settings

Current key creation and lifecycle behavior