API ReferenceAuthentication & API Keys

Authentication

v2.0StableLast updated: January 2026

ThinkHive supports two authentication methods: API Keys and Session Tokens.

API Keys

API Keys are the recommended method for server-to-server integrations.

Getting an API Key

  1. Log in to app.thinkhive.ai
  2. Navigate to Settings > API Keys
  3. Click Create API Key
  4. Select the agent this key will be used for
  5. Configure permissions (read/write/delete)
  6. Copy and securely store your key
⚠️

Security: API keys are shown only once at creation. Store them securely and never expose them in client-side code or public repositories.

Using API Keys

Include the key in the Authorization header:

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

API Key Format

ThinkHive API keys use the format: thk_[random_string]

Example: thk_8f3a7b2c9d4e5f6a7b8c9d0e1f2a3b4c

Key Tiers

TierRate LimitFeatures
Free10/minBasic access
Standard100/min+ Quality metrics
Professional300/min+ RAG eval, hallucinations
Enterprise1,000/minAll features + custom limits

Key Permissions

Each API key can have granular permissions:

PermissionDescription
readView traces, cases, evaluations
writeCreate traces, run evaluations
deleteDelete traces and data

Validate Key

POST /api/v1/explainer/validate-key
 
Response:
{
  "valid": true,
  "tier": "professional",
  "rateLimit": 300,
  "permissions": {
    "read": true,
    "write": true,
    "delete": false
  },
  "features": ["rag_evaluation", "hallucination_detection", "roi_analytics"]
}

Session Authentication

For browser-based applications using Auth0 SSO.

Auth0 Configuration

GET /api/auth/config
 
Response:
{
  "domain": "thinkhive.auth0.com",
  "clientId": "your_client_id",
  "audience": "https://app.thinkhive.ai"
}

Login Flow

  1. Redirect to Auth0 login
  2. Auth0 returns authorization code
  3. Exchange code for session token
  4. Use session cookie for subsequent requests

Session-Based Requests

# Session cookie is automatically included
curl -X GET "https://app.thinkhive.ai/api/agents" \
  --cookie "session=your_session_cookie"

Dual Authentication

Some endpoints support both API Key and Session authentication:

# With API Key
curl -X POST "https://app.thinkhive.ai/api/explainer/analyze" \
  -H "Authorization: Bearer thk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"traces": [...]}'
 
# With Session (browser)
fetch('/api/explainer/analyze', {
  method: 'POST',
  credentials: 'include',  // Include session cookie
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ traces: [...] })
});

Public Endpoints

Some endpoints don’t require authentication:

EndpointMethodDescription
/api/healthGETBasic health check
/api/health/liveGETLiveness probe
/api/health/readyGETReadiness probe
/api/explainer/healthGETExplainer service health
/api/auth/configGETAuth0 configuration

Error Responses

Missing Authentication

HTTP 401 Unauthorized
 
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  }
}

Invalid API Key

HTTP 401 Unauthorized
 
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or expired"
  }
}

Expired Session

HTTP 401 Unauthorized
 
{
  "success": false,
  "error": {
    "code": "SESSION_EXPIRED",
    "message": "Your session has expired. Please log in again."
  }
}

Insufficient Permissions

HTTP 403 Forbidden
 
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Your API key does not have permission for this operation"
  }
}

Best Practices

Environment Variables

const apiKey = process.env.THINKHIVE_API_KEY;
 
const response = await fetch('https://app.thinkhive.ai/api/agents', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

Key Rotation

  1. Generate a new API key in Settings
  2. Update your applications to use the new key
  3. Verify everything works
  4. Revoke the old key via Settings

Security Recommendations

  • Never commit API keys to version control
  • Use environment variables or secret managers
  • Rotate keys regularly (every 90 days recommended)
  • Use minimum permissions required for your use case
  • Monitor key usage in the Settings dashboard
  • Use separate keys for different environments (dev/staging/prod)

API Keys v2

The v2 API key management endpoints provide enhanced key lifecycle management.

Create API Key

POST /api/v2/api-keys

Request Body:

{
  "name": "Production Agent Key",
  "agentId": "agent_abc123",
  "permissions": ["read", "write"],
  "expiresIn": "90d"
}

Response:

{
  "success": true,
  "data": {
    "id": "key_xyz789",
    "name": "Production Agent Key",
    "key": "thk_8f3a7b2c9d4e5f6a7b8c9d0e1f2a3b4c",
    "agentId": "agent_abc123",
    "permissions": ["read", "write"],
    "expiresAt": "2026-06-10T00:00:00Z",
    "createdAt": "2026-03-10T00:00:00Z"
  }
}
⚠️

The full API key is only returned once at creation. Store it securely immediately.

List API Keys

GET /api/v2/api-keys

Get API Key

GET /api/v2/api-keys/:id

Update API Key

PATCH /api/v2/api-keys/:id

Request Body:

{
  "name": "Updated Key Name",
  "permissions": ["read"]
}

Delete API Key

DELETE /api/v2/api-keys/:id

Rotate Key

POST /api/v2/api-keys/:id/rotate

Generates a new key value while preserving all settings. The old key is immediately invalidated.

Response:

{
  "success": true,
  "data": {
    "id": "key_xyz789",
    "key": "thk_new_rotated_key_value",
    "rotatedAt": "2026-03-10T12:00:00Z"
  }
}

Test Key

POST /api/v2/api-keys/:id/test

Validates that the key is active and has the expected permissions.

Response:

{
  "success": true,
  "data": {
    "valid": true,
    "permissions": ["read", "write"],
    "rateLimit": 300,
    "tier": "professional"
  }
}

Key Usage Stats

GET /api/v2/api-keys/:id/usage

Response:

{
  "success": true,
  "data": {
    "totalRequests": 15420,
    "last24h": 342,
    "last7d": 2100,
    "byEndpoint": {
      "/api/traces": 8500,
      "/api/agents": 1200,
      "/v1/guardrails/scan": 5720
    }
  }
}

Agent-Scoped Keys

GET /api/v2/agents/:agentId/api-keys

List all API keys scoped to a specific agent.

Next Steps

OverviewAgents