API Keys

Manage API key pairs for programmatic access to ZenSearch.

Overview

ZenSearch uses a key pair model with two types of keys:

Key Type	Prefix	Use Case
Publishable Key	zsk_pk_	Client-side (browsers, mobile apps)
Secret Key	zsk_sk_	Server-side only

Both keys in a pair share the same permissions and access controls.

Key Pair Architecture

Publishable Keys (zsk_pk_)

Publishable keys are designed for client-side use:

• Safe to embed in frontend code
• Restricted by allowed hosts and referers
• Support IP-based rate limiting
• Limited to read-only operations

note

Publishable keys are browser-safe, but they still grant real access to ZenSearch. Treat them as sensitive operational credentials: scope them narrowly, rotate them when a client is decommissioned, and avoid copying them into tickets, screenshots, or shared docs.

Secret Keys (zsk_sk_)

Secret keys are for server-side use only:

• Never expose in client-side code
• Full access to permitted collections
• Support HMAC request signing
• Can perform write operations

danger

Never expose secret keys in client-side code. Secret keys should only be used in server environments.

Accessing API Keys

1. Click Settings in the sidebar
2. Select the API Keys tab

note

API key management requires Admin or Owner role.

Creating Key Pairs

Create a New Key Pair

1. Click Create API Key
2. Enter a descriptive name
3. Configure collection access
4. Set security restrictions (optional)
5. Click Create

Key Pair Properties

Property	Description
Name	Descriptive name for the key pair
Publishable Key	Client-side key (zsk_pk_...)
Secret Key	Server-side key (zsk_sk_...)
Allowed Collections	Collections the key can access
Rate Limit	Maximum requests per minute
Created	Creation timestamp
Last Used	Last API call timestamp
Expires At	Optional expiration date

Collection Access

Control which collections a key pair can access:

• All Collections: Access any collection in the team
• Specific Collections: Restrict to selected collections only

Security Restrictions

Additional security controls for publishable keys:

Setting	Description
Allowed Hosts	Restrict to specific domains (e.g., docs.example.com)
Allowed Referers	Validate HTTP Referer header
Allowed IPs	Restrict to specific IP addresses or CIDR ranges
Require HMAC Signing	Require request signatures (secret key only)

Managing Keys

View Keys

Keys are only shown once at creation. Store them securely.

To view the key prefix and status:

1. Find the key pair in the list
2. View the masked key prefix (e.g., zsk_pk_abc...)

Rotate Keys

Rotate keys without downtime using the grace period:

1. Click Rotate on the key pair
2. New keys are generated immediately
3. Both old and new keys work during the grace period
4. Update your applications with the new keys
5. Old keys stop working after the grace period (24 hours)

tip

Key rotation maintains a grace period where both old and new keys are valid, allowing zero-downtime updates.

Revoke Keys

To immediately revoke a key pair:

1. Find the key pair in the list
2. Click Revoke (trash icon)
3. Confirm revocation

warning

Revoking a key pair immediately invalidates both the publishable and secret keys. Any applications using these keys will stop working.

Using API Keys

Authentication Header

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

# Using publishable key (client-side)
curl -H "X-ZenSearch-Key: zsk_pk_xxx..." \
  https://api.zensearch.dev/v1/docs/search

# Using secret key (server-side)
curl -H "X-ZenSearch-Key: zsk_sk_xxx..." \
  https://api.zensearch.dev/v1/docs/search

SDK Usage

Documentation Search SDK

import { ZenSearchDocs } from '@zensearch/docs-sdk';

// Client-side: use publishable key
const client = new ZenSearchDocs({
  apiKey: 'zsk_pk_xxx...',
  defaultCollection: 'your-collection-id',
});

const results = await client.search('authentication');

// Server-side: use secret key
const serverClient = new ZenSearchDocs({
  apiKey: process.env.ZENSEARCH_SECRET_KEY, // zsk_sk_xxx...
});

Browser Extension

The ZenSearch browser extension uses a publishable key.

1. Create a dedicated key pair for the extension
2. Copy the publishable key (zsk_pk_...)
3. Paste it into the extension settings page
4. Restrict the key to the collections the extension should search
5. Treat the stored key like endpoint access for that client surface and rotate it if a browser rollout is retired or broadly shared

tip

Create a separate publishable key for the extension instead of reusing one from another client. This makes rotation and access scoping easier.

HMAC Request Signing

For enhanced security on server-side requests, enable HMAC signing:

// Request must include signature headers
const timestamp = Date.now().toString();
const payload = JSON.stringify(requestBody);
const signature = createHmacSha256(secretKey, `${timestamp}.${payload}`);

fetch(url, {
  headers: {
    'X-ZenSearch-Key': 'zsk_sk_xxx...',
    'X-ZenSearch-Timestamp': timestamp,
    'X-ZenSearch-Signature': signature,
  },
});

Rate Limits

Default Limits

Setting	Default	Description
Rate Limit	100/min	Requests per minute per key
IP Rate Limit	20/min	Requests per minute per IP (publishable keys)

Rate Limit Headers

Responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1609459200

Custom Limits

Contact support or use self-hosted deployment for custom rate limits.

Best Practices

Security

1. Use publishable keys for client-side code - They're designed for browser exposure
2. Keep secret keys on the server - Never commit to version control or expose in frontend
3. Use environment variables - Store keys in .env files or secret managers
4. Restrict by collection - Only grant access to required collections
5. Set allowed hosts - Restrict publishable keys to your domains
6. Enable HMAC signing - For sensitive server-side operations
7. Set expiration dates - For temporary or contractor access
8. Treat publishable keys as operational credentials - Safe for approved clients, but still worth rotation and careful handling

Naming Conventions

Use descriptive names that indicate purpose and environment:

• docs-site-production
• internal-tools-staging
• mobile-app-ios
• api-integration-partner-x

Key Rotation Schedule

Recommended rotation frequency:

Environment	Frequency
Production	Every 90 days
Staging	Every 30 days
Development	As needed

Troubleshooting

Invalid Key Error

1. Verify the key prefix matches the expected type (zsk_pk_ or zsk_sk_)
2. Check the key hasn't been revoked
3. Ensure you're using the complete key (not truncated)
4. Verify the key belongs to the correct team

Collection Access Denied

1. Check the key pair's allowed collections
2. Verify the collection ID is correct
3. Ensure the collection exists and is active

Host/Referer Blocked

1. Verify your domain is in the allowed hosts list
2. Check for typos in the domain configuration
3. For local development, add localhost to allowed hosts

Rate Limited

1. Check current usage in the dashboard
2. Implement exponential backoff
3. Cache responses where possible
4. Consider upgrading rate limits

HMAC Signature Invalid

1. Verify the timestamp is within 5 minutes of server time
2. Check the signature algorithm (HMAC-SHA256)
3. Ensure the payload matches exactly
4. Verify you're using the secret key, not publishable key

Next Steps

• API Authentication - Detailed authentication guide
• Docs SDK - JavaScript/TypeScript SDK for documentation search
• Rate Limits - Usage limits and quotas