All Lightfast API requests require authentication. 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:

bash
curl -X POST https://lightfast.ai/api/v1/search \
  -H "Authorization: Bearer sk-lf-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication implementation"}'
curl -X POST https://lightfast.ai/api/v1/search \
  -H "Authorization: Bearer sk-lf-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication implementation"}'

Required Headers:

The organization is resolved automatically from the API key's database record — no additional headers are needed.

Session Authentication

For the Console UI, authentication uses Clerk session cookies with an X-Org-ID header:

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

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

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)

API keys are scoped to your organization. All requests made with a key are automatically associated with the organization that created it.

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

// Bad - hardcoded credentials
const apiKey = 'sk-lf-abc123...'
// Good - load from environment
const apiKey = process.env.LIGHTFAST_API_KEY

// Bad - hardcoded credentials
const apiKey = 'sk-lf-abc123...'

Environment Setup

bash
# .env.local
LIGHTFAST_API_KEY=sk-lf-your-api-key
# .env.local
LIGHTFAST_API_KEY=sk-lf-your-api-key

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}`,
    '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}`,
    '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}`,
    '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 'FORBIDDEN':
      console.error('No access to this organization')
      break
  }
}
const response = await fetch('https://lightfast.ai/api/v1/search', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    '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 'FORBIDDEN':
      console.error('No access to this organization')
      break
  }
}

Example: Complete Request

typescript
async function search(query: string) {
  const response = await fetch('https://lightfast.ai/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
      '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 search('how does authentication work?')
async function search(query: string) {
  const response = await fetch('https://lightfast.ai/api/v1/search', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${process.env.LIGHTFAST_API_KEY}`,
      '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 search('how does authentication work?')

Next Steps

• POST /v1/search — Search your team's knowledge
• Error Handling — Complete error code reference