Kalimalab

Authentication

All API requests to KalimaLab require an API key. Learn how to find, use, and secure your key.

Getting your API key

API keys are created and managed in Dashboard → API Keys. Click "Create API Key", give it a name (e.g. "production", "development"), and click "Create".

How to find your key in the dashboard:

  1. 1Sign in to kalimalab.com and open the Dashboard.
  2. 2Click "API Keys" in the left sidebar.
  3. 3Click "Create API Key", enter a descriptive label (e.g. "production"), and confirm.
  4. 4Copy the displayed key — it starts with klmt_live_.
  5. 5Paste it into your .env file or secrets manager immediately.

⚠Copy immediately

The API key is shown only once at creation time. If you lose it, you must revoke it and create a new one. Store it in a secrets manager or .env file right away.

You can also revoke any key at any time from the same API Keys page. Revocation takes effect within milliseconds — see Error Handling for the response callers will receive.

Two authentication methods

KalimaLab accepts an API key in either the Authorization header (recommended) or an x-api-key header.

RecommendedBearer token (Authorization header)

bash
curl https://api.kalimalab.com/v1/words/random \  -H "Authorization: Bearer klmt_live_your_key"
typescript
const response = await fetch('https://api.kalimalab.com/v1/words/random', {  headers: {    Authorization: `Bearer ${process.env.KALIMALAB_API_KEY}`,  },})

x-api-key header

bash
curl https://api.kalimalab.com/v1/words/random \  -H "x-api-key: klmt_live_your_key"
typescript
const response = await fetch('https://api.kalimalab.com/v1/words/random', {  headers: {    'x-api-key': process.env.KALIMALAB_API_KEY!,  },})

Side-by-side comparison (cURL)

bash
# Method 1: Bearer token (recommended)curl https://api.kalimalab.com/v1/words \  -H "Authorization: Bearer klmt_live_your_key_here"# Method 2: x-api-key headercurl https://api.kalimalab.com/v1/words \  -H "x-api-key: klmt_live_your_key_here"

SDK (handles authentication automatically)

typescript
import { KalimaLab } from '@kalimalab/sdk'// The SDK reads KALIMALAB_API_KEY from environment by defaultconst client = new KalimaLab({ apiKey: process.env.KALIMALAB_API_KEY! })// All requests are automatically authenticatedconst word = await client.words.random()

✕Never expose your key client-side

API keys must only be used in server-side code. Never embed them in browser JavaScript, React component files, mobile app bundles, or public git repositories. Anyone who obtains your key can make requests that count against your quota and billing.

Security best practices

Never expose your key client-side

API keys must only be used server-side. Never embed them in browser JavaScript, mobile app bundles, or public repositories.

Use environment variables

Store keys in .env files (never committed to git) or in your deployment platform's secrets manager (Vercel, Fly.io, Railway, etc.).

One key per environment

Create separate keys for development, staging, and production. This way you can revoke a compromised key without affecting other environments.

Rotate keys periodically

Create a new key, update your environment variables, then revoke the old key. Zero downtime if you follow this order.

Using environment variables in Node.js

.env
# .env (never commit this file)KALIMALAB_API_KEY=klmt_live_your_key_here
lib/kalimalab.ts
import { KalimaLab } from '@kalimalab/sdk'if (!process.env.KALIMALAB_API_KEY) {  throw new Error('KALIMALAB_API_KEY is not set')}export const kalimalab = new KalimaLab({  apiKey: process.env.KALIMALAB_API_KEY,})

Key rotation

To rotate an API key with zero downtime, follow this sequence:

  1. 1Go to Dashboard → API Keys and click "Create API Key".
  2. 2Give it the same name as the key you are rotating (e.g. "Production").
  3. 3Update your production environment variable to use the new key.
  4. 4Deploy / restart your service.
  5. 5After confirming the new key works, return to API Keys and revoke the old key.

What happens when a key is revoked?

Revoked keys are rejected immediately — within milliseconds of revocation. Any request made with a revoked key will receive:

json
{  "data": null,  "error": {    "code": "ERR_AUTH_REVOKED",    "message": "This API key has been revoked. Generate a new key from your dashboard."  },  "meta": { "requestId": "req_01j9..." }}

✕Revocation is permanent

Once revoked, a key cannot be re-activated. You must create a new one.

Authentication error codes

CodeHTTP StatusMeaning
ERR_AUTH_MISSING401No API key was provided in the request headers.
ERR_AUTH_INVALID401API key does not exist or was entered incorrectly.
ERR_AUTH_REVOKED401API key exists but has been revoked.
Edit this page on GitHub
PreviousQuickstartNextRate Limits