Authentication

Chatevo supports two authentication modes depending on who calls the API.

Authentication modes

Mode	Use case	How to authenticate
Session cookie	Dashboard UI, Agent Builder, browser-based admin	Log in at `https://app.chatevo.ai`; session cookie sent automatically
API key	Server integrations, CI/CD, Direct API deployments	`Authorization: Bearer <api_key>` header

Widget endpoints use deployment-scoped auth (deployment ID + allowed domain, optional JWT). They do not accept organization API keys from the browser.

API keys

Create keys under Settings → API keys in the dashboard.

GET https://api.chatevo.ai/api/v1/assistants
Authorization: Bearer ch_live_a1b2c3d4e5f6g7h8
Accept: application/json

Key types

Prefix	Scope	Notes
`ch_live_`	Production	Full access to resources in your organization
`ch_test_`	Sandbox	Same API surface; isolated test data where supported

Key permissions

Keys inherit the permissions of the user who created them. Use a dedicated service account or admin user for automation. Keys can be revoked instantly from the dashboard.

Storage

Never commit API keys to source control.
Store in a secrets manager (Vault, AWS Secrets Manager, etc.).
Rotate keys periodically and after team member offboarding.

Session authentication

After email/password or Google OAuth login, the dashboard receives an HTTP-only, Secure, SameSite session cookie.

Property	Value
Transport	HTTPS only (TLS 1.2+)
Cookie flags	`HttpOnly`, `Secure`, `SameSite=Lax`
Lifetime	Sliding expiration; re-auth required after idle timeout

Session cookies are appropriate for dashboard and Agent Builder requests. Do not embed session cookies in public websites.

Public widget traffic is authenticated differently:

Check	Purpose
`deployment_id`	Identifies the widget deployment
`Origin` / `Referer`	Must match allowed domains
JWT (optional)	Identity verification for logged-in users

See Widget config and Widget messages.

Tool credentials

When assistants call your external APIs, Chatevo uses stored credentials (API keys, OAuth tokens, HMAC secrets) configured under Credentials. These are encrypted at rest and never returned in API responses or exposed to widget visitors.

Error responses

Status	Code	Fix
`401`	`unauthorized`	Missing or invalid API key / expired session
`403`	`forbidden`	Valid auth but insufficient role (e.g. viewer calling admin-only endpoint)