API Keys

Overview

API keys are used to authenticate requests to the Kawn Console AI endpoints (Embeddings, OCR, etc.). Each key is scoped to an organization and grants access to all resources within it.

When you create an API key, the full key is displayed only once. After that, only a hint (the first few characters) is shown for identification. Store your key securely — it cannot be retrieved later.

Authentication

Include your API key in the x-api-key header:

curl https://api-dev.kawn.io/v1/embeddings \
  -H "x-api-key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "tbyaan/islamic-embedding-tbyaan-v1", "input": "..."}'

Alternatively, you can use the Authorization header with a Bearer prefix:

curl https://api-dev.kawn.io/v1/embeddings \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"model": "tbyaan/islamic-embedding-tbyaan-v1", "input": "..."}'

Managing API Keys

Dashboard

You can manage API keys from the API Keys page in the Kawn Console dashboard. From there you can create new keys, see existing keys with their hints and creation dates, and delete keys you no longer need.

API Endpoints

API key management is also available programmatically. These endpoints require JWT authentication (not API key auth) and the appropriate permissions.

Create API Key

POST /api-keys

Creates a new API key for the current organization.

Required Permission: create-api-keys

Request Body

Response

{
  "key": "kc_a1b2c3d4e5f6g7h8i9j0..."
}

Example

curl -X POST https://api-dev.kawn.io/api-keys \
  -H "Authorization: Bearer <JWT_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Production Key"}'

List API Keys

GET /api-keys

Returns a paginated list of API keys for the current organization.

Required Permission: get-api-keys

Query Parameters

Response

{
  "total": 2,
  "page": 1,
  "perPage": 10,
  "apiKeys": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "updatedAt": "2026-03-15T10:30:00.000Z",
      "name": "Production Key",
      "hint": "kc_a1b2c3d4e5"
    },
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "createdAt": "2026-03-20T14:00:00.000Z",
      "updatedAt": "2026-03-20T14:00:00.000Z",
      "name": "Development Key",
      "hint": "kc_x9y8z7w6v5"
    }
  ]
}

Example

curl "https://api-dev.kawn.io/api-keys?page=1&perPage=10" \
  -H "Authorization: Bearer <JWT_TOKEN>"

Delete API Key

DELETE /api-keys/{id}

Permanently deletes an API key. Any requests using this key will immediately stop working.

Required Permission: delete-api-keys

Path Parameters

Response

{
  "message": "Api key deleted successfully."
}

Example

curl -X DELETE https://api-dev.kawn.io/api-keys/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer <JWT_TOKEN>"

Security Best Practices

• Never commit API keys to version control. Use environment variables or a secrets manager.
• Rotate keys periodically. Create a new key, update your applications, then delete the old one.
• Use descriptive names. Name keys after the service or environment they're used in (e.g., "Production Backend", "Staging CI/CD").
• Limit access. Assign the create-api-keys, get-api-keys, and delete-api-keys permissions only to roles that need them.