API keys & authentication
An API key identifies your account on every request. Kaonic issues each key as a pair: a public identifier you can log and display, and a private secret you must keep secret. There are two ways to generate a key — through the dashboard, or programmatically — and both take seconds.
Anatomy of a key
| Part | Prefix | Where it is used | Visible later? |
|---|---|---|---|
| Public key | KG_… |
Read-only requests, logs, dashboards. | Yes — always listed. |
| Private key | GK_… |
Authenticating write and generative requests. | No — returned once. |
| Key ID | kk_… |
Referring to the key when listing or revoking. | Yes. |
| Device key | kai_dev_… |
Hardware telemetry, signed with a device secret. | Secret returned once. |
Option 1 — Generate a key from the dashboard
This is the fastest route and needs no code at all.
- Create your account. Open the developer signup form and enter your name, email and (optionally) your company and password.
- Sign in. You will land on the developer dashboard.
-
Name the key. In the Create API key panel, give the key a
label that describes where it will live — for example
Production serverorWordPress plugin. - Press Create key. Kaonic generates the pair and shows the private key once, in a highlighted box at the top of the dashboard. Copy it before navigating away.
- Track it. The Your API keys table lists every key with its label, public prefix, revocation state and last-used timestamp.
- Revoke when done. Press Revoke beside a key to disable it immediately. Revocation is permanent.
POST /api/dev/keys (form action create)
and revoked with action revoke. The dashboard is simply a friendly front end
for those two calls, protected by a session cookie and CSRF token.
Option 2 — Generate a key programmatically
For CI pipelines, provisioning scripts or embedding Kaonic into your own admin panel, call the key API directly with a bearer token.
Step 1 — Get a bearer token
curl -X POST https://ai.gatavaseug.com/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "you@example.com",
"password": "your-password"
}'
The response carries the token used in the next call:
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
"user": { "id": "usr_...", "email": "you@example.com" }
}
Step 2 — Create the key
curl -X POST https://ai.gatavaseug.com/api/keys/generate \
-H "Authorization: Bearer $KAONIC_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"project": "Production server",
"permissions": ["read", "write"]
}'
Kaonic answers with the pair. This is the only time private_key is returned:
{
"key_id": "kk_3f9c1a72e5b04d18",
"public_key": "KG_8F2C41A9D0E7B356C1480AF92D1E7B54",
"private_key": "GK_A31D9C4E7B2F8065D1A4C39E7F20516B4D8A0C7E93F261504B8DA7C3E091F2AF",
"project": "Production server",
"permissions": ["read", "write"],
"warning": "Store the private_key now — it will never be shown again.",
"created_at": "2026-11-14T09:12:44+00:00"
}
Step 3 — List and revoke
POST /api/keys/list returns every key with private values masked, so it is safe
to display inside your own dashboard:
curl -X POST https://ai.gatavaseug.com/api/keys/list \
-H "Authorization: Bearer $KAONIC_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'
curl -X POST https://ai.gatavaseug.com/api/keys/revoke \
-H "Authorization: Bearer $KAONIC_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "key_id": "kk_3f9c1a72e5b04d18" }'
Using a key on a request
Send the private key in the X-Kaonic-Key header. If your HTTP client cannot set
custom headers, use Authorization: Bearer <key> instead — both are
accepted.
cURL
curl -X POST https://ai.gatavaseug.com/api/ask \
-H "Content-Type: application/json" \
-H "X-Kaonic-Key: GK_A31D9C4E7B2F8065..." \
-d '{"question":"Draft a WhatsApp promotion for my restaurant"}'
PHP
<?php
$ch = curl_init('https://ai.gatavase.com/api/ask');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'X-Kaonic-Key: ' . getenv('KAONIC_API_KEY'),
],
CURLOPT_POSTFIELDS => json_encode([
'question' => 'Draft a WhatsApp promotion for my restaurant',
]),
]);
$response = json_decode(curl_exec($ch), true);
curl_close($ch);
echo $response['answer'] ?? '';
JavaScript / TypeScript
const response = await fetch("https://ai.gatavase.com/api/ask", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-Kaonic-Key": process.env.KAONIC_API_KEY!,
},
body: JSON.stringify({ question: "Draft a WhatsApp promotion for my restaurant" }),
});
const { answer } = await response.json();
console.log(answer);
Permissions and scopes
Grant the narrowest scope that still does the job. A public key (KG_…) is
always limited to read behaviour; write requests must present the private key.
| Permission | Unlocks |
|---|---|
read |
Question answering, listing your keys, reading metrics. |
write |
Creating keys, generators, publishing and mutating resources. |
admin |
Full access to every endpoint on the account. |
voice_synthesis |
Voice endpoints (/api/v1/voice, speech generation). |
music_generation |
Music and jingle generation. |
hologram_voice |
Hologram and presenter speech endpoints. |
Device keys for hardware
Drones, robots, vehicles and kiosks authenticate with a device key rather than an API key. Register the device to receive the pair, then sign every request:
| Header | Value |
|---|---|
X-Kaonic-Device-Key | The kai_dev_… key. |
X-Kaonic-Device-Timestamp | Unix seconds. Rejected if more than 300s skew. |
X-Kaonic-Device-Signature | HMAC-SHA256(METHOD|PATH|TIMESTAMP|BODY, device_secret) |
curl -X POST https://ai.gatavaseug.com/api/v1/devices/register \
-H "X-Kaonic-Key: GK_..." \
-H "Content-Type: application/json" \
-d '{ "name": "Field tablet 01" }'
Security checklist
- Keep private keys in environment variables or a secret manager — never in client code or git.
- Use one key per environment so a leak can be revoked without downtime elsewhere.
- Prefer
read-only keys for dashboards and analytics jobs. - Rotate keys on a schedule: create the new key, deploy, then revoke the old one.
- Watch
last_used_atin the dashboard — unexpected activity means revoke first, investigate second.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
401 invalid_key |
The key is missing, mistyped, or revoked. Confirm you are sending the GK_… private key and not the KG_… public one. |
403 permission_denied |
The key lacks the required scope, or a public key was used for a write. Create a key with the right permission. |
429 rate_limited |
Daily allowance for the key is exhausted, or a burst limit was hit. Wait, or issue a separate key per workload. |
| Key created but rejected everywhere | The private key was copied with whitespace. Trim the value before storing it. |