Get started

Authentication

The Kawaa API uses API keys to authenticate requests. You can create and manage your API keys in the Dashboard.

Using your API key

Include your API key in the X-Api-Key header with every request:

HTTP header

X-Api-Key: ev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The same key is also accepted as a bearer token, for HTTP clients that only know how to send an Authorization header. Send one or the other, not both; when both are present X-Api-Key wins.

HTTP header (alternative)

Authorization: Bearer ev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

An agent can also sign in with OAuth instead of holding a key, and sends the short-lived access token it receives (evo_…) the same way, as a bearer token.

API key format

Prefix: ev_ followed by 32 alphanumeric characters.

Generate keys from your dashboard. Each key can be named for easy identification.

Getting your API key

Sign in to your Kawaa Dashboard
Navigate to Settings → API keys
Click "Create API key" and give it a name
Copy and securely store your key (it won't be shown again)

Security best practices

Never expose your API key in client-side code or public repositories
Use environment variables to store your keys
Rotate your keys periodically and if you suspect they've been compromised
Use separate keys for development and production environments

Authentication errors

Status	Code	Description
401	`UNAUTHORIZED`	Missing or invalid API key or access token
401	`OAUTH_TOKEN_EXPIRED`	A connected app’s access token is past its hour. The app refreshes it with its refresh token and retries; an app that was not issued a refresh token, or whose refresh is refused, signs in again.
403	`INSUFFICIENT_SCOPE`	The credential is valid but is not scoped for this route. For an API key, issue one that carries the scope named in the message. For an app connected by signing in, connect it again asking for that scope as well as the ones it already has (a new sign-in replaces them; they are listed in `granted_scopes`) — unless the message says a connected app can never be given it; then use an API key with every scope the message names, or have the account owner do it in the dashboard.
403	`PLAN_UPGRADE_REQUIRED`	Your plan does not include the feature. No key reaches it, whatever its scopes — the fix is a plan change.
403	`FORBIDDEN`	Access denied for a reason neither of the above covers.

Example request

cURL

curl -X POST https://api.kawaa.com/v1/verify \
  -H "X-Api-Key: ev_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"email": "test@example.com"}'