Skip to main content

​
Authentication

All API requests to KlayrAI require authentication via an API key passed in the request headers. API access is available on the Agency plan.

​
API keys

API keys are scoped to your workspace and inherit the permissions of the workspace owner. Each workspace can have up to 5 active API keys.

​
Creating a key

  1. Open your dashboard at app.klayrai.com
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Give the key a descriptive name (e.g., “Production”, “Staging”)
  5. Copy the key immediately — it will only be shown once
Store your API key in a secure location such as an environment variable or a secrets manager. Never commit API keys to version control or embed them in client-side code.

​
Rotating a key

To rotate a key without downtime:
  1. Create a new API key
  2. Update your application to use the new key
  3. Verify that requests succeed with the new key
  4. Revoke the old key

​
Revoking a key

  1. Navigate to Settings > API Keys
  2. Click the Revoke button next to the key
  3. Confirm the action
Revoked keys are immediately invalidated. Any in-flight requests using the revoked key will fail with a 401 error.

​
Required headers

Every API request must include the following headers:
HeaderRequiredDescription
x-api-keyYesYour API key
klayrai-versionRecommendedAPI version date string (e.g., 2026-03-01). If omitted, the latest version is used. Pinning a version protects your integration from breaking changes.
Content-TypeYes (for POST/PUT)Must be application/json for request bodies

​
Example request

curl -X GET "https://api.klayrai.com/v1/campaigns" \
  -H "x-api-key: klyr_live_abc123def456ghi789" \
  -H "klayrai-version: 2026-03-01" \
  -H "Content-Type: application/json"

​
Key format

API keys follow this format: 
klyr_live_<32 alphanumeric characters>
klyr_test_<32 alphanumeric characters>
  • klyr_live_ keys access production data
  • klyr_test_ keys access sandbox data (coming soon)

​
Authentication errors

StatusError codeDescription
401authentication_errorMissing or invalid API key
401key_revokedThe API key has been revoked
403permission_errorThe API key does not have access to this resource
403plan_insufficientYour plan does not include API access (upgrade to Agency)

​
Example error response

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key. Check that your API key is correct and has not been revoked."
  }
}

​
Security best practices

Store your API key in an environment variable rather than hardcoding it:
export KLAYRAI_API_KEY="klyr_live_abc123def456ghi789"
Then reference it in your code:
const apiKey = process.env.KLAYRAI_API_KEY;
Create separate API keys for development, staging, and production. This limits the blast radius if a key is compromised.
Review API key activity in your dashboard under Settings > API Keys > Usage. Look for unexpected spikes in request volume or requests from unfamiliar IP addresses.
Rotate your API keys every 90 days as a best practice. Use the rotation process described above to avoid downtime.