Skip to main content

API Authentication

All HornetHive API requests require authentication using API keys. This guide covers how to obtain, use, and manage your API keys securely.

Getting Your API Key​

Via Web Dashboard​

  1. Log in to app.hornethive.ai
  2. Navigate to Settings → API Keys
  3. Click "Generate New Key"
  4. Copy and securely store your key
  5. Name your key for easy identification

Key Properties​

Each API key includes:

  • Key ID: Unique identifier for the key
  • Name: Human-readable name you assign
  • Permissions: Scoped access levels
  • Created Date: When the key was generated
  • Last Used: Most recent API call timestamp

Using API Keys​

Authorization Header​

Include your API key in the Authorization header with the Bearer prefix:

curl -H "Authorization: Bearer hive_sk_1234567890abcdef" \
     https://api.hornethive.ai/v1/crews

Request Examples​

JavaScript/Node.js:

const response = await fetch('https://api.hornethive.ai/v1/crews', {
  headers: {
    'Authorization': 'Bearer hive_sk_1234567890abcdef',
    'Content-Type': 'application/json'
  }
});

Python:

import requests

headers = {
    'Authorization': 'Bearer hive_sk_1234567890abcdef',
    'Content-Type': 'application/json'
}

response = requests.get('https://api.hornethive.ai/v1/crews', headers=headers)

cURL:

curl -X GET "https://api.hornethive.ai/v1/crews" \
  -H "Authorization: Bearer hive_sk_1234567890abcdef" \
  -H "Content-Type: application/json"

API Key Permissions​

Permission Scopes​

API keys can be scoped to specific permissions:

Read Permissions:

  • crews:read - List and view crew information
  • outcomes:read - View outcome status and results
  • integrations:read - View integration configurations

Write Permissions:

  • crews:write - Deploy crews and create outcomes
  • outcomes:write - Request revisions and updates
  • integrations:write - Configure and manage integrations

Admin Permissions:

  • admin:read - View admin dashboard and analytics
  • admin:write - Manage users and organization settings

Creating Scoped Keys​

When creating an API key, you can limit its permissions:

{
  "name": "Production Blog Automation",
  "permissions": [
    "crews:read",
    "crews:write",
    "outcomes:read",
    "outcomes:write"
  ],
  "expires_at": "2024-12-31T23:59:59Z"
}

Security Best Practices​

1. Keep Keys Secret​

✅ Do:

  • Store keys in environment variables
  • Use secure key management systems
  • Rotate keys regularly
  • Use different keys for different environments

❌ Don't:

  • Commit keys to version control
  • Include keys in client-side code
  • Share keys via email or chat
  • Use the same key across multiple applications

2. Environment Variables​

Store API keys in environment variables:

# .env file
HORNETHIVE_API_KEY=hive_sk_1234567890abcdef
// Node.js
const apiKey = process.env.HORNETHIVE_API_KEY;
# Python
import os
api_key = os.getenv('HORNETHIVE_API_KEY')

3. Key Rotation​

Regularly rotate your API keys:

  1. Generate a new API key
  2. Update your applications with the new key
  3. Test that everything works correctly
  4. Delete the old API key

4. Monitor Usage​

Regularly review API key usage:

  • Check the "Last Used" timestamp
  • Monitor for unexpected usage patterns
  • Review API logs for suspicious activity
  • Set up alerts for unusual activity

Error Handling​

Authentication Errors​

401 Unauthorized:

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

403 Forbidden:

{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions",
    "details": {
      "required_permission": "crews:write",
      "provided_permissions": ["crews:read"]
    }
  }
}

Common Issues​

Missing Authorization Header:

# ❌ Missing header
curl https://api.hornethive.ai/v1/crews

# ✅ Correct usage
curl -H "Authorization: Bearer hive_sk_..." https://api.hornethive.ai/v1/crews

Incorrect Bearer Format:

# ❌ Missing "Bearer" prefix
curl -H "Authorization: hive_sk_..." https://api.hornethive.ai/v1/crews

# ✅ Correct format
curl -H "Authorization: Bearer hive_sk_..." https://api.hornethive.ai/v1/crews

Rate Limiting​

API keys are subject to rate limits based on your subscription plan:

PlanRequests/minuteConcurrent outcomes
Explorer603
Operator30010
Swarm100025
HiveCoreCustomCustom

Rate Limit Headers​

All API responses include rate limit information:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Handling Rate Limits​

Implement exponential backoff when you hit rate limits:

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);
    
    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    return response;
  }
  
  throw new Error('Max retries exceeded');
}

API Key Management​

Listing Keys​

View all your API keys:

curl -H "Authorization: Bearer hive_sk_..." \
     https://api.hornethive.ai/v1/api-keys

Revoking Keys​

Delete an API key:

curl -X DELETE \
  -H "Authorization: Bearer hive_sk_..." \
  https://api.hornethive.ai/v1/api-keys/{key_id}

Key Metadata​

Update key metadata:

curl -X PATCH \
  -H "Authorization: Bearer hive_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Key Name"}' \
  https://api.hornethive.ai/v1/api-keys/{key_id}

Testing Authentication​

Verify Your Key​

Test your API key with a simple request:

curl -H "Authorization: Bearer YOUR_API_KEY" \
     https://api.hornethive.ai/v1/auth/verify

Success Response:

{
  "valid": true,
  "key_id": "key_1234567890",
  "permissions": ["crews:read", "crews:write"],
  "rate_limit": {
    "limit": 1000,
    "remaining": 999,
    "reset": 1640995200
  }
}

SDK Authentication​

Node.js SDK:

import { HornetHive } from '@hornethive/api';

const client = new HornetHive(process.env.HORNETHIVE_API_KEY);

// Test authentication
try {
  const auth = await client.auth.verify();
  console.log('Authentication successful:', auth);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Python SDK:

from hornethive import HornetHive

client = HornetHive(os.getenv('HORNETHIVE_API_KEY'))

# Test authentication
try:
    auth = client.auth.verify()
    print('Authentication successful:', auth)
except Exception as error:
    print('Authentication failed:', str(error))

Support​

If you're having authentication issues:

  1. Check that your API key is correct and hasn't been revoked
  2. Verify the Authorization header format
  3. Confirm your key has the required permissions
  4. Review our troubleshooting guide
  5. Contact support at hello@hornethive.ai

Next Steps: