AirdraftAirdraft
Get started
All guides

API Keys

Create and manage API keys to authenticate server-side and third-party requests to your Airdraft CMS.

2 min read370 words

API keys let server-side code and external tools make authenticated requests to your CMS without a user session. Every project has its own set of API keys.

Key format

Airdraft API keys follow the format ntk_xxxxxxxxxxxxxxxx. The full key is shown once at creation — Airdraft stores only a hash. If you lose it, generate a new one.

Creating an API key

Airdraft Cloud

  1. Go to your project's Settings → API Keys.
  2. Click New API key.
  3. Enter a descriptive name (e.g. Next.js site — production).
  4. Optionally set an expiry date.
  5. Click Create.
  6. Copy the key immediately — it cannot be retrieved again.

Self-hosted

For self-hosted setups, the CMS_API_KEY environment variable acts as the primary admin key:

# .env.local
CMS_API_KEY=ntk_xxxxxxxxxxxxxxxx

Generate a secure key:

npx airdraft generate-secret

You can also issue scoped keys via the API or the admin UI if you have the @airdraft/plugin-auth plugin installed.

Using an API key

Include the key in the X-API-Key header:

curl https://api.airdraft.space/cms/<project-id>/entries/posts \
  -H "X-API-Key: ntk_xxxxxxxxxxxxxxxx"

Or via the TypeScript client:

import { AirdraftClient } from '@airdraft/client'

const cms = new AirdraftClient({
  apiUrl: process.env.CMS_API_URL!,
  auth: { type: 'apiKey', token: process.env.CMS_API_KEY! },
})

Or as a Bearer token:

curl https://api.airdraft.space/cms/<project-id>/entries/posts \
  -H "Authorization: Bearer ntk_xxxxxxxxxxxxxxxx"

Important: API keys are admin-level credentials. Never expose them in client-side JavaScript or commit them to version control. Store them in environment variables only.

Embed tokens (public/client-side access)

For browser-based access to published content, use an embed token instead of an API key. Embed tokens are origin-scoped, short-lived, and safe to expose in client-side code.

Generate one server-side using @airdraft/auth:

import { generateEmbedToken } from '@airdraft/auth'

const token = generateEmbedToken(
  {
    projectId: 'proj_123',
    allowedOrigin: 'https://mysite.com',
    ttlSeconds: 3600,   // default 3600, max 86400
  },
  process.env.AIRDRAFT_JWT_SECRET!,
)

Use it client-side:

import { AirdraftClient } from '@airdraft/client'

const client = new AirdraftClient({
  apiUrl: process.env.NEXT_PUBLIC_CMS_API_URL!,
  auth: { type: 'embedToken', token },
})

Embed tokens can only read published content — they cannot create, update, or delete entries.

Revoking a key

Airdraft Cloud

Go to Settings → API Keys, click the ⋯ menu next to the key, and click Revoke. The key is invalidated immediately.

Self-hosted

Remove the key from your environment variables and restart the server. If you issued keys via the API, delete them via DELETE /api/cms/auth/keys/:id.

Security best practices

  • One key per integration — use separate keys for different services so you can revoke one without affecting others.
  • Set expiry dates for keys given to contractors or temporary integrations.
  • Never commit keys to version control — use .env.local or your deployment platform's secrets manager.
  • Rotate immediately if you suspect a key has been exposed.

Related guides