API Key Management

API keys are the primary way to authenticate with ThinkHive’s API. This guide covers creating, securing, rotating, and managing keys across your environments.

Creating API Keys

Navigate to Settings

Go to Settings → API Keys in the ThinkHive dashboard.

Click Create API Key

Provide a descriptive name (e.g., production-ingestion, staging-readonly).

Select an agent

Each API key is scoped to a specific agent. Choose the agent this key will be used with.

Configure permissions

Permission	Description
`read`	View traces, cases, evaluations, and analytics
`write`	Create traces, run evaluations, trigger analysis
`delete`	Delete traces, cases, and associated data

Copy and store securely

⚠️

Your API key is displayed only once at creation. Copy it immediately and store it in a secure location such as a secret manager or encrypted environment variable file.

API Key Format

ThinkHive API keys follow the format: thk_[32-character-hex-string]

Example: thk_8f3a7b2c9d4e5f6a7b8c9d0e1f2a3b4c

Using API Keys

Include the key in the Authorization header as a Bearer token:

curl -X GET "https://app.thinkhive.ai/api/v1/agents" \
  -H "Authorization: Bearer thk_your_api_key"

// With the SDK (recommended)
import { ThinkHive } from 'thinkhive-js';
 
const th = new ThinkHive({
  apiKey: process.env.THINKHIVE_API_KEY,
  endpoint: 'https://app.thinkhive.ai',
  serviceName: 'my-agent'
});
 
// Direct API call
const response = await fetch('https://app.thinkhive.ai/api/v1/agents', {
  headers: { 'Authorization': `Bearer ${process.env.THINKHIVE_API_KEY}` }
});

# With the SDK (recommended)
import thinkhive
import os
 
thinkhive.init(
    api_key=os.environ["THINKHIVE_API_KEY"],
    endpoint="https://app.thinkhive.ai",
    service_name="my-agent"
)
 
# Direct API call
import requests
 
response = requests.get(
    "https://app.thinkhive.ai/api/v1/agents",
    headers={"Authorization": f"Bearer {os.environ['THINKHIVE_API_KEY']}"}
)

Key Tiers & Rate Limits

Each API key has an associated tier that determines rate limits and available features:

Tier	Rate Limit	Features
Free	10 req/min	Basic tracing, explainability
Standard	100 req/min	+ Search, patterns, quality metrics
Professional	300 req/min	+ RAG eval, hallucinations, ROI analytics
Enterprise	1,000 req/min	All features + custom limits

When rate limited, the API returns HTTP 429 with headers indicating when you can retry:

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706123456
Retry-After: 30

Key Rotation

Rotate API keys regularly to maintain security. Recommended rotation interval: every 90 days.

Create a new API key

Generate a new key with the same permissions as the existing one.

Update your applications

Deploy the new key to all services that use it. Use environment variables or a secret manager to make this process seamless.

Verify the new key works

Run a health check or test request with the new key:

curl -X POST "https://app.thinkhive.ai/api/v1/explainer/validate-key" \
  -H "Authorization: Bearer thk_your_new_key"

Revoke the old key

Once all services are using the new key, revoke the old one in Settings → API Keys.

Security Best Practices

Store keys securely

🚫

Never commit API keys to version control, embed them in client-side code, or share them in plaintext.

Use environment variables or a secret manager:

# .env file (never commit this)
THINKHIVE_API_KEY=thk_your_api_key

Add .env to your .gitignore:

# .gitignore
.env
.env.local
.env.production

Use separate keys per environment

Environment	Key Name	Permissions
Development	`dev-local`	`read`, `write`
Staging	`staging-ci`	`read`, `write`
Production	`prod-ingestion`	`write` only
Production	`prod-dashboard`	`read` only

Apply least-privilege permissions

Only grant the permissions your integration needs. A trace ingestion service only needs write; a dashboard only needs read.

Monitor key usage

Check key usage in Settings → API Keys → Usage. Look for:

Unexpected spikes in request volume
Requests from unknown IP ranges
Failed authentication attempts

Validate keys on startup

Add key validation to your application startup:

const th = new ThinkHive({
  apiKey: process.env.THINKHIVE_API_KEY,
  endpoint: 'https://app.thinkhive.ai',
  serviceName: 'my-agent'
});
 
// Validate on startup
const validation = await th.validateKey();
if (!validation.valid) {
  throw new Error('Invalid ThinkHive API key');
}
console.log(`Key tier: ${validation.tier}, rate limit: ${validation.rateLimit}/min`);

Troubleshooting

”Invalid API Key” error

Verify the key hasn’t been revoked
Check for extra whitespace or truncation when copying the key
Ensure the key starts with thk_
Confirm the key has the required permissions for the endpoint

”Rate Limited” (HTTP 429)

Check the Retry-After header for when to retry
Consider upgrading your tier if you consistently hit limits
Implement exponential backoff in your client — see Troubleshooting

Key not working after rotation

Verify the old key was not cached in application memory (restart may be needed)
Check that all services have been updated to the new key
Confirm the new key has the same permissions as the old one

Next Steps

Authentication — Full authentication reference
API Reference — Complete endpoint documentation
JavaScript SDK — SDK setup with API keys
Python SDK — Python SDK setup

Guardrail Policies Webhooks