Authentication

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

Access Your Dashboard

Log into your JobHive dashboard at app.jobhive.ai

Navigate to API Settings

Go to Settings → API Keys in the main navigation

Generate New Key

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

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"

const response = await fetch('https://backend.jobhive.ai/v1/interviews', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer jh_live_abc123def456ghi789',
    'Content-Type': 'application/json'
  }
});

import requests

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

response = requests.get('https://backend.jobhive.ai/v1/interviews', headers=headers)

API Key Types & Environments

Key Formats

JobHive API keys follow a consistent format for easy identification:

Environment	Format	Example
Development	`jh_dev_*`	`jh_dev_abc123def456`
Production	`jh_live_*`	`jh_live_xyz789ghi012`
Test Mode	`jh_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

// Using environment variables
const apiKey = process.env.JOBHIVE_API_KEY;
const environment = process.env.JOBHIVE_ENVIRONMENT || 'development';

if (!apiKey) {
  throw new Error('JOBHIVE_API_KEY environment variable is required');
}

const client = new JobHive({
  apiKey: apiKey,
  environment: environment
});

import os
from jobhive import JobHive

api_key = os.environ.get('JOBHIVE_API_KEY')
environment = os.environ.get('JOBHIVE_ENVIRONMENT', 'development')

if not api_key:
    raise ValueError('JOBHIVE_API_KEY environment variable is required')

client = JobHive(
    api_key=api_key,
    environment=environment
)

Key Rotation

Regular API key rotation is a security best practice:

Generate New Key

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

Update Applications

Deploy the new key to all applications and environments

Monitor Usage

Verify that all systems are using the new key successfully

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"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked.",
    "details": {
      "key_prefix": "jh_live_abc123"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "API_KEY_EXPIRED",
    "message": "Your API key has expired. Please generate a new one.",
    "details": {
      "expired_at": "2024-01-15T10:30:00Z",
      "renewal_url": "https://app.jobhive.ai/settings/api-keys"
    }
  }
}

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Your API key does not have permission for this operation.",
    "details": {
      "required_permission": "interviews:write",
      "current_permissions": ["interviews:read"]
    }
  }
}

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;
}

import requests
from requests.exceptions import HTTPError

def make_authenticated_request(url, **kwargs):
    headers = kwargs.get('headers', {})
    headers.update({
        'Authorization': f'Bearer {os.environ["JOBHIVE_API_KEY"]}',
        'Content-Type': 'application/json'
    })
    kwargs['headers'] = headers
    
    response = requests.request(**kwargs)
    
    if response.status_code == 401:
        error_data = response.json()
        error_code = error_data['error']['code']
        
        if error_code == 'AUTHENTICATION_REQUIRED':
            raise AuthenticationError('API key is missing from request')
        elif error_code == 'INVALID_API_KEY':
            raise AuthenticationError('API key is invalid - check your environment')
        elif error_code == 'API_KEY_EXPIRED':
            raise AuthenticationError('API key has expired - generate a new one')
        else:
            raise AuthenticationError(f'Authentication failed: {error_data["error"]["message"]}')
    
    response.raise_for_status()
    return response

API Key Permissions

Permission Scopes

API keys can be configured with specific permission scopes to limit access:

Permission	Description	Example Usage
`interviews:read`	View interview data and results	Dashboard analytics
`interviews:write`	Create and update interviews	Scheduling system
`interviews:delete`	Cancel and delete interviews	Admin operations
`webhooks:read`	View webhook configurations	Integration status
`webhooks:write`	Create and manage webhooks	Event handling setup
`analytics:read`	Access aggregate analytics	Reporting systems

Creating Scoped Keys

Navigate to API Keys

Go to Settings → API Keys in your dashboard

Click Advanced Options

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

Select Permissions

Choose only the permissions your application needs

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;
}

import time
import requests

def make_rate_limited_request(url, **kwargs):
    response = requests.request(**kwargs)
    
    if response.status_code == 429:
        retry_after = int(response.headers.get('X-RateLimit-Retry-After', 60))
        print(f"Rate limited. Retrying after {retry_after} seconds")
        
        time.sleep(retry_after)
        return make_rate_limited_request(url, **kwargs)  # 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"

async function testApiKey() {
  try {
    const response = await fetch('https://backend.jobhive.ai/v1/account/profile', {
      headers: {
        'Authorization': `Bearer ${process.env.JOBHIVE_API_KEY}`
      }
    });
    
    if (response.ok) {
      const profile = await response.json();
      console.log('API key is valid:', profile.data.company_name);
    } else {
      console.error('API key test failed:', response.status);
    }
  } catch (error) {
    console.error('API key test error:', error.message);
  }
}

def test_api_key():
    try:
        response = requests.get(
            'https://backend.jobhive.ai/v1/account/profile',
            headers={'Authorization': f'Bearer {os.environ["JOBHIVE_API_KEY"]}'}
        )
        
        if response.status_code == 200:
            profile = response.json()
            print(f'API key is valid: {profile["data"]["company_name"]}')
        else:
            print(f'API key test failed: {response.status_code}')
    except Exception as error:
        print(f'API key test error: {error}')

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.

Getting Started

Core Resources

Advanced Features

API Key Authentication

Getting Your API Key

Authentication Format

Example Requests

API Key Types & Environments

Key Formats

Environment Separation

Security Best Practices

API Key Management

Secure Storage

Usage Protection

Environment Variable Setup

Key Rotation

Error Handling

Authentication Errors

Handling Authentication Errors

API Key Permissions

Permission Scopes

Creating Scoped Keys

Rate Limiting & Quotas

Rate Limit Headers

Handling Rate Limits

Testing Authentication

Verify API Key

​API Key Authentication

​Getting Your API Key

​Authentication Format

​Example Requests

​API Key Types & Environments

​Key Formats

​Environment Separation

​Security Best Practices

​API Key Management

Secure Storage

Usage Protection

​Environment Variable Setup

​Key Rotation

​Error Handling

​Authentication Errors

​Handling Authentication Errors

​API Key Permissions

​Permission Scopes

​Creating Scoped Keys

​Rate Limiting & Quotas

​Rate Limit Headers

​Handling Rate Limits

​Testing Authentication

​Verify API Key

API Key Authentication

Getting Your API Key

Authentication Format

Example Requests

API Key Types & Environments

Key Formats

Environment Separation

Security Best Practices

API Key Management

Environment Variable Setup

Key Rotation

Error Handling

Authentication Errors

Handling Authentication Errors

API Key Permissions

Permission Scopes

Creating Scoped Keys

Rate Limiting & Quotas

Rate Limit Headers

Handling Rate Limits

Testing Authentication

Verify API Key