All Lightfast API requests require authentication and a workspace identifier. The API supports two authentication methods: API keys for external clients and session authentication for the Console UI.

Authentication Methods

API Key Authentication

For external API clients, use an API key in the Authorization header along with the X-Workspace-ID header:

bash
curl -X POST https://lightfast.ai/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication implementation"}'
curl -X POST https://lightfast.ai/api/v1/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "X-Workspace-ID: ws_abc123" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication implementation"}'

Required Headers:

Session Authentication

For the Console UI, authentication uses Clerk session cookies. The X-Workspace-ID header is still required:

bash
# Session auth (used by Console UI)
Cookie: __session=<clerk-session>
X-Workspace-ID: ws_abc123
# Session auth (used by Console UI)
Cookie: __session=<clerk-session>
X-Workspace-ID: ws_abc123

Session authentication validates that the user is a member of the organization that owns the workspace.

Getting Your API Key

1. Sign in to the Lightfast Console
2. Navigate to Settings → API Keys
3. Click Create New Key
4. Copy the key immediately (it won't be shown again)

Getting Your Workspace ID

Your workspace ID can be found in:

• The Console URL: https://lightfast.ai/{org}/{workspace} → workspace ID is in settings
• Settings → Workspace → Workspace ID

Security Best Practices

Use Environment Variables

Never hardcode API keys in your source code:

typescript
// ✅ Good - load from environment
const apiKey = process.env.LIGHTFAST_API_KEY
const workspaceId = process.env.LIGHTFAST_WORKSPACE_ID

// ❌ Bad - hardcoded credentials
const apiKey = 'lf_abc123...'
// ✅ Good - load from environment
const apiKey = process.env.LIGHTFAST_API_KEY
const workspaceId = process.env.LIGHTFAST_WORKSPACE_ID

// ❌ Bad - hardcoded credentials
const apiKey = 'lf_abc123...'

Environment Setup

bash
# .env.local
LIGHTFAST_API_KEY=your-api-key
LIGHTFAST_WORKSPACE_ID=ws_abc123
# .env.local
LIGHTFAST_API_KEY=your-api-key
LIGHTFAST_WORKSPACE_ID=ws_abc123

Never Commit Keys

Add environment files to .gitignore:

bash
# .gitignore
.env
.env.local
.env.production
# .gitignore
.env
.env.local
.env.production

Server-Side Only

API keys should only be used in server-side code:

typescript
// ✅ Server-side (Node.js, API routes, server actions)
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'X-Workspace-ID': process.env.LIGHTFAST_WORKSPACE_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'authentication' })
})

// ❌ Never expose API keys in client-side code
// ✅ Server-side (Node.js, API routes, server actions)
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
    'X-Workspace-ID': process.env.LIGHTFAST_WORKSPACE_ID,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'authentication' })
})

// ❌ Never expose API keys in client-side code

Error Responses

Authentication errors return JSON with an error code and message:

json
{
  "error": "UNAUTHORIZED",
  "message": "Authentication required. Provide 'Authorization: Bearer <api-key>' header or sign in.",
  "requestId": "req_abc123"
}
{
  "error": "UNAUTHORIZED",
  "message": "Authentication required. Provide 'Authorization: Bearer <api-key>' header or sign in.",
  "requestId": "req_abc123"
}

Error Codes

Handling Errors

typescript
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Workspace-ID': workspaceId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'search query' })
})

if (!response.ok) {
  const error = await response.json()

  switch (error.error) {
    case 'UNAUTHORIZED':
      console.error('Invalid or missing API key')
      break
    case 'BAD_REQUEST':
      console.error('Missing X-Workspace-ID header')
      break
    case 'FORBIDDEN':
      console.error('No access to this workspace')
      break
    case 'NOT_FOUND':
      console.error('Workspace not found')
      break
  }
}
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Workspace-ID': workspaceId,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ query: 'search query' })
})

if (!response.ok) {
  const error = await response.json()

  switch (error.error) {
    case 'UNAUTHORIZED':
      console.error('Invalid or missing API key')
      break
    case 'BAD_REQUEST':
      console.error('Missing X-Workspace-ID header')
      break
    case 'FORBIDDEN':
      console.error('No access to this workspace')
      break
    case 'NOT_FOUND':
      console.error('Workspace not found')
      break
  }
}

Example: Complete Request

typescript
async function searchWorkspace(query: string) {
  const response = await fetch('https://lightfast.ai/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
      'X-Workspace-ID': process.env.LIGHTFAST_WORKSPACE_ID!,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query })
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(`API error: ${error.message}`)
  }

  return response.json()
}

// Usage
const results = await searchWorkspace('how does authentication work?')
async function searchWorkspace(query: string) {
  const response = await fetch('https://lightfast.ai/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
      'X-Workspace-ID': process.env.LIGHTFAST_WORKSPACE_ID!,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ query })
  })

  if (!response.ok) {
    const error = await response.json()
    throw new Error(`API error: ${error.message}`)
  }

  return response.json()
}

// Usage
const results = await searchWorkspace('how does authentication work?')

Next Steps

• POST /v1/search - Search your team's knowledge
• POST /v1/contents - Retrieve full content by ID
• POST /v1/findsimilar - Find semantically similar content
• Error Handling - Complete error code reference