​

Authentication Overview

​

Authentication Methods

​

Comparison

​

When to Use Each Method

​

Anonymous Access

• Testing the API without an account
• Public datasets only
• Prototyping or demos

• 50 requests per hour
• Read-only access to public datasets
• No document uploads
• No dataset creation

curl https://api.fltr.com/v1/datasets/public-dataset-id/query \
  -H "Content-Type: application/json" \
  -d '{"query": "search term"}'

​

API Keys

• Building backend services
• Running scheduled jobs or cron tasks
• Integrating with no-code platforms (Zapier, Make, n8n)
• Deploying production applications

• Simple to implement
• 1,000 requests per hour
• Full access to your account’s resources
• Can be rotated and revoked

curl https://api.fltr.com/v1/datasets \
  -H "Authorization: Bearer fltr_sk_abc123..."

​

OAuth 2.1

• Building MCP integrations (Claude Desktop, VS Code, Cursor)
• Creating web applications with user authentication
• Need fine-grained permission scopes
• Require the highest rate limits

• 15,000 requests per hour
• PKCE flow for enhanced security
• Scope-based permissions
• Automatic token refresh

# OAuth flow handles authentication
# Your app receives an access token
headers = {
    "Authorization": f"Bearer {access_token}"
}

​

Session Tokens

• Building single-page applications (SPAs)
• Creating admin dashboards
• Need browser-based authentication

• 15,000 requests per hour
• HTTP-only cookies for security
• CSRF protection built-in
• Automatic session management

// After login, session cookie is set automatically
fetch('https://api.fltr.com/v1/datasets', {
  credentials: 'include'  // Sends session cookie
})

​

Rate Limits

Anonymous:    50 requests/hour
API Key:      1,000 requests/hour
OAuth/Session: 15,000 requests/hour

​

Rate Limit Headers

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704657600

​

Security Best Practices

​

For API Keys

• ✅ Store keys in environment variables
• ✅ Use different keys for dev/staging/prod
• ✅ Rotate keys periodically (every 90 days)
• ✅ Revoke compromised keys immediately
• ✅ Use server-side code only

• ❌ Commit keys to version control
• ❌ Embed keys in client-side JavaScript
• ❌ Share keys via email or chat
• ❌ Use the same key across multiple projects

​

For OAuth

• ✅ Always use PKCE flow
• ✅ Validate redirect URIs
• ✅ Store tokens securely (encrypted storage)
• ✅ Use HTTPS for all OAuth flows
• ✅ Implement token refresh logic

• ❌ Store tokens in localStorage (use httpOnly cookies)
• ❌ Skip state parameter validation
• ❌ Use implicit flow (deprecated)

​

For Sessions

• ✅ Enable HTTP-only cookies
• ✅ Use SameSite=Strict or Lax
• ✅ Implement CSRF protection
• ✅ Set secure flag in production
• ✅ Use short session lifetimes

• ❌ Store sensitive data in cookies
• ❌ Accept credentials over HTTP
• ❌ Skip CSRF validation

​

Authentication Errors

​

401 Unauthorized

{
  "error": "Invalid API key",
  "code": "invalid_api_key"
}

• Invalid or expired API key
• Missing Authorization header
• Malformed Bearer token

# Correct format
Authorization: Bearer fltr_sk_abc123...

# Not this
Authorization: fltr_sk_abc123...
Authorization: Bearer: fltr_sk_abc123...

​

403 Forbidden

{
  "error": "Insufficient permissions",
  "code": "insufficient_scope"
}

• OAuth scope doesn’t include required permission
• Trying to access another user’s resources
• Account suspended

​

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retry_after": 3600,
  "code": "rate_limit_exceeded"
}

• Wait for retry_after seconds
• Implement exponential backoff
• Upgrade to OAuth for higher limits
• Cache frequent queries

​

Migration Guide

​

From Anonymous → API Key

1. Create account at www.tryfltr.com
2. Generate API key in Settings → API Keys
3. Add Authorization header to all requests:

  curl https://api.fltr.com/v1/datasets/ds_123/query \
+   -H "Authorization: Bearer fltr_sk_abc123..." \
    -H "Content-Type: application/json" \
    -d '{"query": "search term"}'

​

From API Key → OAuth

1. Register OAuth application in dashboard
2. Implement PKCE authorization flow
3. Exchange authorization code for access token
4. Replace API key with access token:

  headers = {
-   "Authorization": "Bearer fltr_sk_abc123..."
+   "Authorization": f"Bearer {access_token}"
  }

​

Quick Reference

​

API Key Format

fltr_sk_abc123def456ghi789...
       │  └─────────────────── Random identifier
       └────────────────────── Secret key prefix

​

OAuth Scopes

datasets:read     Read datasets and documents
datasets:write    Create and modify datasets
datasets:delete   Delete datasets and documents
mcp:query        Use MCP query endpoints
webhooks:manage   Create and manage webhooks

​

HTTP Status Codes

200 OK              Request successful
201 Created         Resource created successfully
400 Bad Request     Invalid request parameters
401 Unauthorized    Invalid or missing authentication
403 Forbidden       Insufficient permissions
404 Not Found       Resource doesn't exist
429 Too Many Reqs   Rate limit exceeded
500 Server Error    Internal server error

​

Next Steps