Authentication

Overview

The CollectIQ API uses API keys for authentication. Every request (except /health and public scan tracking) must include a valid API key in the Authorization header.

GET /api/v1/buyer-requests HTTP/1.1
Host: collectiqhq.com
Authorization: Bearer ciq_live_a1b2c3d4e5f6...
Content-Type: application/json

Creating API Keys

1. Navigate to Portal → API Keys
2. Click "Create API Key" and give it a descriptive name
3. Select the scopes the key needs (or leave blank for full access)
4. Copy the secret immediately — it's shown only once

SDK Authentication

import { createCollectIQ } from '@collectiq/sdk';

const ciq = createCollectIQ({
  baseUrl: 'https://collectiqhq.com/api',
  apiKey: process.env.COLLECTIQ_API_KEY,
});

// All requests are now authenticated
const requests = await ciq.buyerRequests.list();

cURL Example

curl -X GET https://collectiqhq.com/api/v1/buyer-requests \
  -H "Authorization: Bearer ciq_live_a1b2c3d4..." \
  -H "Content-Type: application/json"

Scopes

API keys can be scoped to limit access. Available scopes:

Error Responses

{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid API key"
}

{
  "code": "INSUFFICIENT_SCOPE",
  "message": "API key lacks required scope: write:inventory"
}

{
  "code": "RATE_LIMITED",
  "message": "Too many requests. Retry after 60 seconds.",
  "details": { "retry_after": 60 }
}

Rate Limiting

API requests are rate-limited per workspace. The SDK automatically retries on 429 responses with exponential backoff.