Skip to main content

​
API Key Authentication

JobHive uses API key authentication to secure all API endpoints. Your API key must be included in the Authorization header of every request.

​
Getting Your API Key

1

Access Your Dashboard

Log into your JobHive dashboard at app.jobhive.ai
2

Navigate to API Settings

Go to Settings → API Keys in the main navigation
3

Generate New Key

Click “Generate New API Key” and provide a descriptive name for identification
4

Copy and Store Securely

Copy your API key immediately - it will only be shown once. Store it securely in your environment variables.

​
Authentication Format

Include your API key in the Authorization header using the Bearer token format: 
Authorization: Bearer YOUR_API_KEY

​
Example Requests

curl -X GET "https://backend.jobhive.ai/v1/interviews" \
  -H "Authorization: Bearer jh_live_abc123def456ghi789" \
  -H "Content-Type: application/json"

​
API Key Types & Environments

​
Key Formats

JobHive API keys follow a consistent format for easy identification:
EnvironmentFormatExample
Developmentjh_dev_*jh_dev_abc123def456
Productionjh_live_*jh_live_xyz789ghi012
Test Modejh_test_*jh_test_mno345pqr678

​
Environment Separation

  • Development Keys
  • Production Keys
  • Test Mode Keys
Purpose: Local development and testingFeatures:
  • Access to sandbox environment
  • Unlimited test interviews
  • No billing or credit consumption
  • Separate data isolation
Limitations:
  • Cannot create production interviews
  • Results not stored permanently
  • Limited to development features

​
Security Best Practices

​
API Key Management

Secure Storage

Do’s
  • Store in environment variables
  • Use secret management systems
  • Rotate keys regularly (quarterly)
  • Use different keys per environment

Usage Protection

Don’ts
  • Never commit keys to version control
  • Don’t expose in client-side code
  • Avoid logging keys in application logs
  • Don’t share keys via email or chat

​
Environment Variable Setup

# JobHive API Configuration
JOBHIVE_API_KEY=jh_live_your_production_key_here
JOBHIVE_WEBHOOK_SECRET=whsec_your_webhook_secret_here
JOBHIVE_ENVIRONMENT=production

# Development overrides
# JOBHIVE_API_KEY=jh_dev_your_development_key_here  
# JOBHIVE_ENVIRONMENT=development

​
Key Rotation

Regular API key rotation is a security best practice:
1

Generate New Key

Create a new API key in your dashboard before the current one expires
2

Update Applications

Deploy the new key to all applications and environments
3

Monitor Usage

Verify that all systems are using the new key successfully
4

Revoke Old Key

Delete the old API key from your dashboard once migration is complete

​
Error Handling

​
Authentication Errors

{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_REQUIRED",
    "message": "API key is required. Include 'Authorization: Bearer YOUR_API_KEY' header.",
    "details": {
      "header_missing": "Authorization"
    }
  }
}

​
Handling Authentication Errors

async function makeAuthenticatedRequest(url, options = {}) {
  const response = await fetch(url, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.JOBHIVE_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers
    }
  });

  if (response.status === 401) {
    const error = await response.json();
    
    switch (error.error.code) {
      case 'AUTHENTICATION_REQUIRED':
        throw new Error('API key is missing from request');
      case 'INVALID_API_KEY':
        throw new Error('API key is invalid - check your environment variables');
      case 'API_KEY_EXPIRED':
        throw new Error('API key has expired - generate a new one');
      default:
        throw new Error(`Authentication failed: ${error.error.message}`);
    }
  }

  return response;
}

​
API Key Permissions

​
Permission Scopes

API keys can be configured with specific permission scopes to limit access:
PermissionDescriptionExample Usage
interviews:readView interview data and resultsDashboard analytics
interviews:writeCreate and update interviewsScheduling system
interviews:deleteCancel and delete interviewsAdmin operations
webhooks:readView webhook configurationsIntegration status
webhooks:writeCreate and manage webhooksEvent handling setup
analytics:readAccess aggregate analyticsReporting systems

​
Creating Scoped Keys

1

Navigate to API Keys

Go to Settings → API Keys in your dashboard
2

Click Advanced Options

Select “Create Key with Custom Permissions” instead of default key
3

Select Permissions

Choose only the permissions your application needs
4

Set Expiration

Optionally set an expiration date for additional security

​
Rate Limiting & Quotas

​
Rate Limit Headers

All API responses include rate limiting information: 
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299  
X-RateLimit-Reset: 1640995200
X-RateLimit-Retry-After: 60

​
Handling Rate Limits

async function makeRateLimitedRequest(url, options) {
  const response = await fetch(url, options);
  
  if (response.status === 429) {
    const retryAfter = response.headers.get('X-RateLimit-Retry-After');
    console.log(`Rate limited. Retrying after ${retryAfter} seconds`);
    
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return makeRateLimitedRequest(url, options); // Retry
  }
  
  return response;
}

​
Testing Authentication

​
Verify API Key

Test your API key with a simple request: 
curl -X GET "https://backend.jobhive.ai/v1/account/profile" \
  -H "Authorization: Bearer YOUR_API_KEY"
Expected successful response: 
{
  "success": true,
  "data": {
    "company_name": "Your Company",
    "plan": "Professional",
    "api_key_permissions": ["interviews:read", "interviews:write"],
    "rate_limit": {
      "requests_per_minute": 300,
      "current_usage": 1
    }
  }
}
Security Tip: Always test API keys in development before deploying to production. Use the account profile endpoint to verify both authentication and permissions.
Important: API keys provide full access to your JobHive account. Treat them like passwords and follow security best practices to protect your data and prevent unauthorized usage.