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.

An API key is read from these two headers only

The key must be the whole value of X-Api-Key, or follow Bearer and one space in Authorization (header names and the word Bearer are case-insensitive). Anywhere else the key is not seen at all. The only other credential the API reads is the dashboard’s own sign-in cookie, which a script does not normally send, so a script’s request fails with 401 UNAUTHORIZED and the message API key is required, not “invalid key”. A misplaced key includes:

Authorization: ev_… without Bearer, or with another scheme such as Token or Basic
any other header name, such as Api-Key or X-Kawaa-Key
a query parameter such as ?api_key=ev_…, which would also leave the key in logs

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	`API_KEY_REVOKED`	The credential no longer works: it was deleted, revoked or deactivated, or a change on the account retired it. Create a new API key in the dashboard, or connect an app that signed in again. Two cases have another remedy, and their message names it: a sub-account key replaced by a key reset (use the key the reset returned), and a credential turned off while an account deletion is pending (use the cancellation link in the deletion email).
401	`API_KEY_SUSPENDED`	The key is suspended because the subscription ended or is unpaid. Pay the outstanding invoice or restart the subscription and the same key works again, or create a new key to use the credits left on the account.
401	`EMAIL_VERIFICATION_REQUIRED`	The account’s email address has not been verified yet, so its key is not active. Open the link in the verification email.
401	`SESSION_EXPIRED`	A dashboard session has ended. Sign in again.
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"}'