Skip to main content

API Authentication

Learn how to authenticate with the ZenSearch API.

API Keys​

Getting an API Key​

  1. Go to Settings → API Keys in ZenSearch
  2. Click Create API Key
  3. Copy and securely store your key
warning

API keys cannot be retrieved after creation. Store them securely.

Using API Keys​

Include the API key in the Authorization header:

curl -X POST https://api.zensearch.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "your search query"}'

SDK Authentication​

JavaScript​

import { ZenSearch } from '@zensearch/sdk';

const client = new ZenSearch({
  apiKey: process.env.ZENSEARCH_API_KEY
});

Python​

from zensearch import ZenSearch

client = ZenSearch(api_key=os.environ["ZENSEARCH_API_KEY"])

Go​

import "github.com/ZenousAI/zensearch-go"

client := zensearch.NewClient(os.Getenv("ZENSEARCH_API_KEY"))

Team Context​

API keys are scoped to a team. All operations use the team context of the key.

To specify a different team (if you have access):

curl -X POST https://api.zensearch.ai/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Team-ID: team_xyz123" \
  -H "Content-Type: application/json" \
  -d '{"query": "search query"}'

Security Best Practices​

Do​

  • Store keys in environment variables
  • Use separate keys for different environments
  • Rotate keys periodically
  • Monitor key usage

Don't​

  • Commit keys to version control
  • Share keys in plain text
  • Use production keys in development
  • Embed keys in client-side code

Error Responses​

Invalid API Key​

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid API key"
  }
}

HTTP Status: 401 Unauthorized

Missing API Key​

{
  "error": {
    "code": "unauthorized",
    "message": "Authorization header required"
  }
}

HTTP Status: 401 Unauthorized

Insufficient Permissions​

{
  "error": {
    "code": "forbidden",
    "message": "API key does not have permission for this operation"
  }
}

HTTP Status: 403 Forbidden

Next Steps​