developers/Authentication

Authentication

All Intufind API requests require a Bearer token in the Authorization header. Intufind issues two key types, each designed for a specific trust boundary.

Key Types

Secret Keys (if_sk_)

Full read/write access — server-side only.

  • Index products, posts, and taxonomies
  • Manage webhooks and prompts
  • Access analytics and tenant management
  • Provision additional API keys

Publishable Keys (if_pk_)

Read-only access — safe for browsers.

  • Perform search queries
  • Send chat messages
  • Submit feedback
  • Automatically scoped to the originating domain via CORS

Use publishable keys in chat widgets, search UIs, and any client-side code.

Making Requests

Include your key as a Bearer token:

curl -X POST https://api.intufind.com/products/search \
  -H "Authorization: Bearer if_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"text": "wireless headphones"}'

JavaScript SDK

import { createClient, searchProducts } from '@intufind/ai-sdk';

const client = createClient({
  baseUrl: 'https://api.intufind.com',
  auth: process.env.INTUFIND_SECRET_KEY!,
});

const { data } = await searchProducts({
  client,
  body: { text: 'wireless headphones' },
});

Workspace Scoping

Every content write (product upsert, post upsert, etc.) must be scoped to a workspace. Include the X-Workspace-ID header:

curl -X POST https://api.intufind.com/products \
  -H "Authorization: Bearer if_sk_xxx" \
  -H "X-Workspace-ID: my-store-com" \
  -H "Content-Type: application/json" \
  -d '{"id": "product-1", "name": "Running Shoes"}'

Search and chat requests also accept X-Workspace-ID to scope results. For browser requests using a publishable key, the workspace is derived automatically from the Origin header.

i
Workspace ID Format
Workspace IDs are lowercase alphanumeric with hyphens (e.g., my-store-com). Dots in domain names are converted to hyphens automatically.

Error Responses

401 Unauthorized

{
  "error": {
    "message": "Invalid or expired API key",
    "code": "UNAUTHORIZED"
  }
}

Verify your key is correct, check the Authorization: Bearer <key> format, and ensure the key hasn't been revoked.

402 Payment Required

{
  "error": {
    "message": "Your free trial has ended",
    "code": "TRIAL_EXPIRED"
  }
}

Subscribe to a plan at intufind.com/pricing. Your data is preserved and will be available once you subscribe.

403 Forbidden

Returned when a publishable key attempts a server-only operation, or the subscription is inactive.

Response Envelope

Successful responses include usage and tier data alongside results:

{
  "data": { "..." },
  "tierLimits": {
    "search": { "enabled": true, "queriesPerMonth": 50000 },
    "chat": { "enabled": true, "messagesPerMonth": 4000 }
  },
  "usage": {
    "rateLimit": {
      "remaining": { "perMinute": 45, "perHour": 950 },
      "resetTime": 1733180400000
    },
    "quota": {
      "current": 150,
      "limit": 10000,
      "resetDate": "2026-04-01"
    }
  }
}

Use this data to monitor rate limits and quotas proactively. See Rate Limits for details.

Security Best Practices

  • Store secret keys in environment variables — never hardcode them
  • Use publishable keys for all client-side code — never expose if_sk_ in browsers
  • Rotate keys periodically — create a new key, update your apps, then delete the old one
  • Use separate keys for development and production
  • Monitor for unauthorized usage in your dashboard analytics

Next Steps