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, update status
`kb:read`	List and view knowledge base entries
`kb:write`	Create, update, and delete KB entries
`customers:read`	List and view customer profiles
`customers:write`	Create and update customer profiles
`workflows:read`	List and view workflows
`workflows:write`	Create and update workflows

Workspace Selection

For multi-workspace accounts, specify the workspace with the X-Workspace-Id header:

curl https://app.keva.support/api/v1/tickets \
  -H "Authorization: Bearer keva_live_your_api_key" \
  -H "X-Workspace-Id: ws_abc123"

Or use the workspace_id query parameter:

curl "https://app.keva.support/api/v1/tickets?workspace_id=ws_abc123" \
  -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 minimal scopes — only grant the permissions needed
Rotate keys regularly — create new keys and revoke old ones periodically
Set expiration dates — use short-lived keys for temporary integrations
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

Webhooks

Receive real-time event notifications