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

PartPrefixWhere it is usedVisible 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.
Store the private key immediately. Kaonic keeps only a SHA-256 hash of it. There is no way to display it again — if you lose it, revoke the key and create a new one.

Option 1 — Generate a key from the dashboard

This is the fastest route and needs no code at all.

  1. Create your account. Open the developer signup form and enter your name, email and (optionally) your company and password.
  2. Sign in. You will land on the developer dashboard.
  3. Name the key. In the Create API key panel, give the key a label that describes where it will live — for example Production server or WordPress plugin.
  4. 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.
  5. Track it. The Your API keys table lists every key with its label, public prefix, revocation state and last-used timestamp.
  6. Revoke when done. Press Revoke beside a key to disable it immediately. Revocation is permanent.
Keys are created through 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.

PermissionUnlocks
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:

HeaderValue
X-Kaonic-Device-KeyThe kai_dev_… key.
X-Kaonic-Device-TimestampUnix seconds. Rejected if more than 300s skew.
X-Kaonic-Device-SignatureHMAC-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

Troubleshooting

SymptomCause 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.