API Keys

Secure your integration with two-tier API key system.

Overview

Home Insight AI uses a two-tier API key system to ensure secure client-side integrations:

• Secret Keys (hi_live_secret_...): Full API access, backend only
• Publishable Keys (hi_live_pub_...): Limited access, safe for client-side use

Key Types Comparison

| Feature | Secret Key | Publishable Key | |---------|-----------|----------------| | Format | hi_live_secret_... | hi_live_pub_... | | Usage | Backend only | Frontend safe | | Domain Restriction | ❌ No | ✅ Yes | | Rate Limiting | 60/min | 60/min | | Chat Access | ✅ Yes | ✅ Yes | | Create Properties | ✅ Yes | ❌ No | | Delete Resources | ✅ Yes | ❌ No | | Billing Access | ✅ Yes | ❌ No |

Create Publishable Key

Generate a client-safe publishable key with domain restrictions.

Endpoint

POST /v1/api-keys/publishable

Authentication

Requires a secret API key in the Authorization header.

Request Body

{
  "name": "Production Website",
  "allowed_domains": [
    "https://yourdomain.com",
    "https://www.yourdomain.com"
  ],
  "permissions": {
    "chat": true,
    "read_properties": true,
    "write_properties": false,
    "billing": false
  }
}

Response

{
  "id": "key_abc123def456",
  "key": "hi_live_pub_XyZ789abcdefGHI...",
  "key_type": "publishable",
  "name": "Production Website",
  "tier": "pro",
  "allowed_domains": [
    "https://yourdomain.com",
    "https://www.yourdomain.com"
  ],
  "permissions": {
    "chat": true,
    "read_properties": true,
    "write_properties": false,
    "billing": false
  },
  "created_at": "2025-12-13T10:30:00Z"
}

Example

curl -X POST https://api.homeinsightai.com/v1/api-keys/publishable \
  -H "Authorization: Bearer hi_live_secret_YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Website",
    "allowed_domains": ["https://yourdomain.com"],
    "permissions": {
      "chat": true,
      "read_properties": true
    }
  }'

List API Keys

Get all API keys for your account (keys are masked for security).

Endpoint

GET /v1/api-keys

Authentication

Requires any valid API key (secret or publishable).

Response

{
  "keys": [
    {
      "id": "key_abc123",
      "key": "hi_live_secr...5678",
      "key_type": "secret",
      "tier": "pro",
      "allowed_domains": [],
      "permissions": {},
      "created_at": "2025-12-01T00:00:00Z",
      "last_used_at": "2025-12-13T09:15:30Z"
    },
    {
      "id": "key_def456",
      "key": "hi_live_pub_...abcd",
      "key_type": "publishable",
      "tier": "pro",
      "allowed_domains": ["https://example.com"],
      "permissions": {"chat": true},
      "created_at": "2025-12-13T10:30:00Z",
      "last_used_at": null
    }
  ]
}

Example

curl https://api.homeinsightai.com/v1/api-keys \
  -H "Authorization: Bearer hi_live_secret_YOUR_SECRET_KEY"

Delete API Key

Revoke an API key permanently.

Endpoint

DELETE /v1/api-keys/{key_id}

Authentication

Requires a secret API key. Publishable keys cannot delete keys.

Response

{
  "message": "API key deleted successfully",
  "id": "key_abc123"
}

Example

curl -X DELETE https://api.homeinsightai.com/v1/api-keys/key_abc123 \
  -H "Authorization: Bearer hi_live_secret_YOUR_SECRET_KEY"

Security Best Practices

✅ Do

• Use publishable keys in client-side applications (React, Vue, Angular, etc.)
• Specify allowed domains to prevent unauthorized usage
• Rotate keys regularly for enhanced security
• Use secret keys only in server-side code
• Monitor key usage via the API

❌ Don't

• Never embed secret keys in client-side code
• Never commit API keys to version control (use .env files)
• Never share API keys publicly (GitHub, Stack Overflow, etc.)
• Never use the same key across multiple applications

Domain Validation

Publishable keys validate requests based on Origin and Referer headers:

Origin: https://yourdomain.com
Referer: https://yourdomain.com/dashboard

If the domain doesn't match your allowed_domains, you'll receive:

{
  "detail": "This API key is not authorized for use from this domain. Allowed domains: https://yourdomain.com"
}

Rate Limiting

All API keys are rate-limited to 60 requests per minute using Redis-based distributed rate limiting.

If you exceed the limit:

{
  "detail": "Rate limit exceeded. Maximum 60 requests per minute allowed."
}

Status Code: 429 Too Many Requests

SDK Integration

React Example

import { HomeInsightChat } from 'home-insight-ai-sdk';

function App() {
  return (
    <HomeInsightChat
      apiKey="hi_live_pub_XyZ789..."  // ✅ Publishable key
      propertyId="prop_abc123"
    />
  );
}

Next.js Example

// .env.local
NEXT_PUBLIC_HOMEINSIGHT_API_KEY=hi_live_pub_XyZ789...

// components/Chat.tsx
export default function Chat() {
  return (
    <HomeInsightChat
      apiKey={process.env.NEXT_PUBLIC_HOMEINSIGHT_API_KEY}
      propertyId={propertyId}
    />
  );
}

Troubleshooting

Error: "Invalid API key"

• Verify the key starts with hi_live_pub_ or hi_live_secret_
• Check that the key hasn't been deleted
• Ensure you're using the correct environment (test vs. production)

Error: "This API key is not authorized for use from this domain"

• Verify your domain is in the allowed_domains list
• Check for typos (e.g., http:// vs https://)
• Ensure you're testing from the correct domain (not localhost if not allowed)

Error: "This endpoint requires a secret API key"

• You're using a publishable key for an endpoint that requires a secret key
• Use your secret key for management operations (create/delete keys, modify billing)

Next Steps

• Chat API - Use your publishable key with the Chat endpoint
• SDK Documentation - Integrate the chat widget in your app
• Webhooks - Get notified of analysis completion