> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitl.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API Keys

> Generate and manage API keys to securely integrate HITL.sh with your applications and workflows

# API Keys

API keys are your secure credentials for integrating HITL.sh with your applications, workflows, and third-party tools. They authenticate your requests and ensure only authorized systems can interact with your loops and data.

## Understanding API Keys

API keys in HITL.sh serve as your application's identity and provide secure access to:

* **Loop Management**: Create, read, update, and delete loops
* **Request Operations**: Submit requests and retrieve responses
* **Loop Members**: Add and remove reviewers from loops
* **Webhook Configuration**: Set up event notifications
* **Request Feedback**: Add feedback to completed requests

> [!WARNING]
>
> Keep your API keys secure and never expose them in client-side code or public repositories. Treat them like passwords.

## Generating Your First API Key

**1. Log In to Dashboard**

Visit [my.hitl.sh](https://my.hitl.sh) and log in to your account.

**2. Navigate to API Keys**

Go to Settings → API Keys from the main navigation menu.

**3. Create New API Key**

Click the "Create New API Key" button to generate a new key.

**4. Copy and Store Securely**

Copy the generated API key immediately and store it securely in environment variables. The key is only shown once for security reasons.

> [!WARNING]
>
> API keys are shown only once when created. Store them immediately in a secure location like environment variables or a secrets manager.

## API Key Management

### Viewing Active Keys

Your dashboard shows all active API keys with their:

* **Name**: Descriptive label for easy identification
* **Permissions**: Access level granted to the key
* **Created Date**: When the key was generated
* **Last Used**: Most recent activity timestamp
* **Status**: Active, suspended, or expired

### API Key Permissions

API keys have specific permissions based on your account and plan:

> [accordion] Loop Operations
>
> * Create, read, update, and delete loops
> * Manage loop members (add/remove reviewers)
> * View loop statistics and activity

> [accordion] Request Operations
>
> * Create requests in loops you own
> * View and cancel your requests
> * Add feedback to completed requests
> * Access request history and responses

> [accordion] Webhook Configuration
>
> * Set up webhook endpoints for real-time notifications
> * Configure webhook events and filters
> * View webhook delivery logs and status

### Security Best Practices

> [card] Environment Variables
>
> Store API keys in environment variables, never hardcode them in your source code.

> [card] Key Rotation
>
> Regularly rotate your API keys to minimize the impact of potential compromises.

> [card] Scope Permissions
>
> Grant only the minimum permissions necessary for each integration.

> [card] Monitor Usage
>
> Regularly review API key usage to detect unauthorized access.

## Using API Keys

### Authentication Header

Include your API key in the `Authorization` header of all API requests:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY_HERE
```

### Testing Your API Key

Use the test endpoint to verify your API key is working correctly:

```bash cURL theme={null}
curl -X GET 'https://api.hitl.sh/v1/test' \
  -H 'Authorization: Bearer YOUR_API_KEY'
```

```python Python theme={null}
import requests

headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
}

response = requests.get('https://api.hitl.sh/v1/test', headers=headers)
data = response.json()

if data["error"] == False:
    print("✅ API key is valid!")
    print(f"Rate limit: {data['data']['rate_limit']['remaining']}/{data['data']['rate_limit']['limit']}")
else:
    print("❌ API key validation failed")
```

```javascript Node.js theme={null}
const axios = require('axios');

const headers = {
    'Authorization': 'Bearer YOUR_API_KEY'
};

async function testApiKey() {
    try {
        const response = await axios.get('https://api.hitl.sh/v1/test', { headers });
        if (!response.data.error) {
            console.log('✅ API key is valid!');
            console.log(`Rate limit: ${response.data.data.rate_limit.remaining}/${response.data.data.rate_limit.limit}`);
        }
    } catch (error) {
        console.error('❌ API key validation failed:', error.response?.data);
    }
}

testApiKey();
```

**Expected Response:**

```json theme={null}
{
  "error": false,
  "msg": "API key is valid",
  "data": {
    "api_key_id": "65f1234567890abcdef12349",
    "user_id": "65f1234567890abcdef12346",
    "email": "user@example.com", 
    "account_status": "active",
    "rate_limit": {
      "limit": 100,
      "remaining": 95,
      "reset_at": "2024-03-15T15:00:00Z"
    },
    "permissions": ["loops:read", "loops:write", "requests:read", "requests:write"]
  }
}
```

## Rate Limits

API keys have usage limits to ensure fair usage:

> [card] Current Rate Limits
>
> * **100 requests per hour** per API key
> * Rate limits reset at the **top of each hour** (e.g., 1:00 PM, 2:00 PM, not rolling 60 minutes)
> * Rate limit information included in response headers
> * `X-RateLimit-Reset` header shows the exact UTC timestamp when the limit resets

**Rate Limit Headers:**

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 85  
X-RateLimit-Reset: 1642237200
```

### Handling Rate Limits

```python theme={null}
import time
import requests

def make_api_request_with_retry(url, headers, data=None, max_retries=3):
    for attempt in range(max_retries):
        try:
            if data:
                response = requests.post(url, headers=headers, json=data)
            else:
                response = requests.get(url, headers=headers)
            
            if response.status_code == 429:
                # Rate limited - wait and retry
                retry_after = int(response.headers.get('Retry-After', 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                continue
                
            return response
            
        except Exception as e:
            if attempt == max_retries - 1:
                raise e
            time.sleep(2 ** attempt)  # Exponential backoff
    
    return None
```

## Integration Examples

### Creating Your First Loop

```python theme={null}
import requests

api_key = "YOUR_API_KEY"
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

# Create a new loop
response = requests.post(
    "https://api.hitl.sh/v1/api/loops",
    headers=headers,
    json={
        "name": "Content Moderation Loop",
        "description": "Review user-generated content for compliance"
    }
)

if response.status_code == 200:
    loop_data = response.json()
    print(f"✅ Loop created: {loop_data['data']['id']}")
```

### Submitting a Request

```javascript theme={null}
const axios = require('axios');

const apiKey = 'YOUR_API_KEY';
const loopId = 'your_loop_id';

const headers = {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
};

async function submitRequest() {
    try {
        const response = await axios.post(
            `https://api.hitl.sh/v1/api/loops/${loopId}/requests`,
            {
                processing_type: 'time-sensitive',
                type: 'markdown',
                priority: 'medium',
                request_text: 'Please review this content for appropriateness.',
                response_type: 'single_select',
                response_config: {
                    options: [
                        { value: 'approve', label: 'Approve' },
                        { value: 'reject', label: 'Reject' }
                    ],
                    required: true
                },
                timeout_seconds: 3600,
                platform: 'api'
            },
            { headers }
        );
        
        console.log('✅ Request submitted:', response.data.data.id);
        return response.data.data;
    } catch (error) {
        console.error('❌ Error submitting request:', error.response?.data);
    }
}

submitRequest();
```

## Troubleshooting

### Common Issues

> [accordion] 401 Unauthorized - Invalid API Key
>
> **Symptoms:** `{"error": true, "msg": "Invalid authorization token"}`
>
> **Solutions:**
>
> * Verify the API key is copied correctly without extra spaces
> * Check if the key has been revoked in your dashboard
> * Ensure you're using the Bearer format: `Authorization: Bearer YOUR_API_KEY`
> * Confirm you're not including extra characters or line breaks

> [accordion] 403 Forbidden - Insufficient Permissions
>
> **Symptoms:** `{"error": true, "msg": "Access denied to this resource"}`
>
> **Solutions:**
>
> * Verify your API key has the required permissions
> * Check if you're trying to access resources you don't own
> * Ensure your account has the necessary features enabled

> [accordion] 429 Rate Limited
>
> **Symptoms:** `{"error": true, "msg": "API rate limit exceeded"}`
>
> **Solutions:**
>
> * Wait for the rate limit to reset (check `X-RateLimit-Reset` header)
> * Implement exponential backoff in your retry logic
> * Use the `/test` endpoint to check your current rate limit status
> * Consider batching requests to optimize usage

> [accordion] Network or Connection Issues
>
> **Symptoms:** Connection timeouts or network errors
>
> **Solutions:**
>
> * Verify you can reach `api.hitl.sh` from your network
> * Check if you're behind a corporate firewall blocking the API
> * Ensure you're using HTTPS (not HTTP) for all requests
> * Try from a different network to isolate connectivity issues

### Debug Authentication

Use this debug script to troubleshoot API key issues:

```python theme={null}
import requests

def debug_api_key(api_key):
    """Debug API key authentication issues"""
    headers = {"Authorization": f"Bearer {api_key}"}
    
    try:
        response = requests.get("https://api.hitl.sh/v1/test", headers=headers)
        
        print(f"Status Code: {response.status_code}")
        print(f"Response: {response.json()}")
        
        if response.status_code == 200:
            data = response.json()["data"]
            print("\n🔍 API Key Debug Info:")
            print(f"   Account: {data['email']}")
            print(f"   Status: {data['account_status']}")
            print(f"   Rate Limit: {data['rate_limit']['remaining']}/{data['rate_limit']['limit']}")
            print(f"   Permissions: {', '.join(data['permissions'])}")
        
    except Exception as e:
        print(f"❌ Error: {e}")

# Test your API key
debug_api_key("YOUR_API_KEY_HERE")
```

## Next Steps

Now that you have your API key set up, you're ready to:

> [card] [Test Your API Key](https://docs.hitl.sh/api-reference/test-api-key.md)
>
> Verify your API key is working with the test endpoint.

> [card] [Create Your First Loop](https://docs.hitl.sh/api-reference/loops/create-loop.md)
>
> Set up a human-in-the-loop workflow using the API.

> [card] [Submit Your First Request](https://docs.hitl.sh/api-reference/requests/create-request.md)
>
> Send content for human review and get responses.

> [card] [API Reference](https://docs.hitl.sh/api-reference/introduction.md)
>
> Explore all available endpoints and integration options.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.