Authentication

Overview

TheFAQApp uses API keys as the authentication mechanism for all API requests. API keys are scoped to an organization and can be created from the dashboard or programmatically via the API.

Every API request must include a valid API key in the Authorization header using the Bearer scheme.

Creating an API Key

Via Dashboard

1. Navigate to Settings > API Keys in your organization dashboard
2. Click Create API Key
3. Enter a name and select the scopes you need
4. Optionally set an expiration date
5. Copy the key immediately -- it is only shown once

Via API

If your existing key has the admin scope, you can create new keys programmatically.

curl -X POST https://app.thefaq.app/api/v1/your-org/api-keys \
  -H "Authorization: Bearer faq_your-admin-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CI/CD Pipeline Key",
    "scopes": ["read", "write"],
    "expiresAt": "2027-01-01T00:00:00.000Z"
  }'

const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/api-keys',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer faq_your-admin-api-key',
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      name: 'CI/CD Pipeline Key',
      scopes: ['read', 'write'],
      expiresAt: '2027-01-01T00:00:00.000Z',
    }),
  }
);

const { data } = await response.json();
// data.key contains the full API key -- store it securely
console.log(data.key); // "faq_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345"

Response:

{
  "data": {
    "id": "clx...",
    "name": "CI/CD Pipeline Key",
    "key": "faq_aBcDeFgHiJkLmNoPqRsTuVwXyZ012345",
    "scopes": ["read", "write"],
    "expiresAt": "2027-01-01T00:00:00.000Z",
    "createdAt": "2026-02-28T10:00:00.000Z"
  }
}

Using Your API Key

Include the key in every request using the Authorization header with the Bearer scheme.

curl https://app.thefaq.app/api/v1/your-org/questions \
  -H "Authorization: Bearer faq_your-api-key"

const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions',
  {
    headers: {
      'Authorization': 'Bearer faq_your-api-key',
    },
  }
);

const { data, meta } = await response.json();

If you are using the SDK, pass the key during client creation:

import { createFaqClient } from '@faq/sdk';

const client = createFaqClient({
  apiKey: process.env.FAQ_API_KEY!,
  organizationSlug: 'your-org',
});

API Key Scopes

Each API key has one or more scopes that control what operations it can perform.

Scope inheritance: A key with admin scope can perform all write and read operations. A key with write scope can also perform read operations.

Which endpoints require which scopes

Error Responses

401 Unauthorized -- Missing or invalid key

curl https://app.thefaq.app/api/v1/your-org/questions
# No Authorization header

const response = await fetch(
  'https://app.thefaq.app/api/v1/your-org/questions'
);
// 401 Unauthorized

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Authorization header. Use: Authorization: Bearer <api-key>"
  }
}

403 Forbidden -- Insufficient scopes

If your key has read scope but you attempt a write operation:

{
  "error": {
    "code": "forbidden",
    "message": "This API key lacks required scope(s): write. Key has: read"
  }
}

See Errors Reference for the full list of error codes.

Security Best Practices

• Never expose API keys in client-side code. API keys should only be used in server-side applications, CI/CD pipelines, or backend services.
• Use environment variables. Store keys in process.env.FAQ_API_KEY rather than hardcoding them.
• Create separate keys per environment. Use different keys for development, staging, and production.
• Use the minimum required scopes. A read-only integration should use a read-scoped key.
• Set expiration dates for temporary integrations or short-lived tokens.
• Rotate keys regularly. Create a new key, update your integration, then delete the old one.
• Monitor usage via the dashboard API Keys page to detect anomalous traffic.