Authentication

All API requests to Home Insight AI must be authenticated using an API key. This guide explains how to create, manage, and use API keys securely.

API Keys

API keys are used to authenticate requests to the Home Insight AI API. Each key is associated with your account and tracks usage for billing purposes.

Key Format

API keys follow this format:

• Test keys: hi_test_... (for development and testing)
• Live keys: hi_live_... (for production use)

Test vs Live Keys

Best Practice: Always use hi_test_ keys during development. Switch to hi_live_ keys only when deploying to production.

Creating an API Key

1. Log in to your dashboard
2. Navigate to the API Keys section
3. Click "Create New API Key"
4. Enter a descriptive name (e.g., "Production App", "Staging Environment")
5. Copy the key immediately - it won't be shown again

Security Best Practice: Never commit API keys to version control. Use environment variables instead.

Making Authenticated Requests

Include your API key in the Authorization header of every request:

curl https://api.homeinsightai.com/v1/analyses \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Example with JavaScript

const response = await fetch('https://api.homeinsightai.com/v1/analyses', {
  headers: {
    'Authorization': `Bearer ${process.env.HOME_INSIGHT_API_KEY}`,
    'Content-Type': 'application/json'
  }
})

Example with Python

import os
import requests

headers = {
    'Authorization': f'Bearer {os.environ["HOME_INSIGHT_API_KEY"]}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://api.homeinsightai.com/v1/analyses',
    headers=headers
)

Managing API Keys

Listing Your Keys

View all your API keys in the dashboard. You'll see:

• Key name
• Prefix (first 12 characters)
• Creation date
• Last used timestamp
• Usage statistics

Rotating Keys

To rotate an API key:

1. Create a new key in the dashboard
2. Update your application to use the new key
3. Verify the new key works in production
4. Delete the old key

Recommended: Rotate keys every 90 days for enhanced security.

Deleting Keys

Deleted keys are immediately revoked and cannot be restored. Any requests using a deleted key will return a 401 Unauthorized error.

Authentication Errors

401 Unauthorized

Cause: Missing or invalid API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

Solution: Verify your API key is correct and included in the Authorization header.

403 Forbidden

Cause: Valid API key but insufficient permissions

{
  "error": {
    "code": "forbidden",
    "message": "This API key does not have access to this resource"
  }
}

Solution: Check that you're using a production (hi_live_) key for production endpoints.

429 Too Many Requests

Cause: Rate limit exceeded for your API key

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please wait before retrying.",
    "retry_after": 60
  }
}

Solution: Implement exponential backoff and respect the retry_after value. See Rate Limits.

Security Best Practices

Environment Variables

Store API keys in environment variables:

# .env file
HOME_INSIGHT_API_KEY=hi_live_abc123xyz

Never hardcode keys in source code:

// ❌ Bad - hardcoded key
const apiKey = 'hi_live_abc123xyz'

// ✅ Good - environment variable
const apiKey = process.env.HOME_INSIGHT_API_KEY

Client-Side vs Server-Side

Never expose production API keys in client-side code. API keys should only be used in:

• Backend servers
• Server-side rendered pages
• Serverless functions

For client-side applications, use the React SDK which handles authentication securely.

Key Scoping

Create separate API keys for different environments:

• Development: hi_test_dev_... for local development
• Staging: hi_test_staging_... for staging environment
• Production: hi_live_prod_... for production

This allows you to:

• Track usage per environment
• Rotate keys without affecting all environments
• Quickly revoke compromised keys

Testing Authentication

Test your API key with a simple health check:

curl https://api.homeinsightai.com/health \
  -H "Authorization: Bearer hi_live_YOUR_API_KEY"

Expected response:

{
  "status": "ok",
  "authenticated": true,
  "account_id": "acc_xyz789"
}

Next Steps

• Quick Start Guide - Make your first API request
• API Reference - Explore all available endpoints
• Rate Limits - Understand usage quotas