API Key Authentication

API keys provide a simple way to authenticate requests to the FLTR API. They’re perfect for server-side applications, scripts, and integrations.

Quick Start

Generate an API Key

Log in to www.tryfltr.com
Navigate to Settings → API Keys
Click Create API Key
Give your key a descriptive name
Copy and save the key securely

Use the API Key

Include your API key in the Authorization header:

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

Test Your Key

Verify the key works by listing your datasets:

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

API Key Format

FLTR API keys follow this format:

fltr_sk_1234567890abcdefghijklmnop
│    │  └────────────────────────── Unique identifier (30 chars)
│    └───────────────────────────── Secret key indicator
└────────────────────────────────── FLTR prefix

Prefix: fltr_ identifies the key as a FLTR credential
Type: sk indicates a secret key
ID: Random alphanumeric string

Using API Keys

In HTTP Requests

Include the API key in the Authorization header with the Bearer scheme:

Authorization: Bearer fltr_sk_abc123...

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

import requests

API_KEY = "fltr_sk_abc123..."
headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
}

response = requests.get(
    "https://api.fltr.com/v1/datasets",
    headers=headers
)

const API_KEY = "fltr_sk_abc123...";

const response = await fetch("https://api.fltr.com/v1/datasets", {
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json"
  }
});

package main

import (
    "net/http"
)

func main() {
    apiKey := "fltr_sk_abc123..."

    req, _ := http.NewRequest("GET", "https://api.fltr.com/v1/datasets", nil)
    req.Header.Set("Authorization", "Bearer " + apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()
}

Environment Variables

Store API keys in environment variables, never hard-code them:

# .env file
FLTR_API_KEY=fltr_sk_abc123...

# Load in shell
export FLTR_API_KEY="fltr_sk_abc123..."

import os
from dotenv import load_dotenv

load_dotenv()

API_KEY = os.getenv("FLTR_API_KEY")

// Using dotenv
require('dotenv').config();

const API_KEY = process.env.FLTR_API_KEY;

SDK Usage

Official SDKs are coming soon. For now, use the REST API directly with your preferred HTTP client.

Key Management

Creating Keys

You can have multiple API keys for different purposes: Recommended naming conventions:

production-api - Production server
staging-api - Staging environment
ci-cd-pipeline - Automated testing
zapier-integration - Zapier workflows

Per environment:

Create separate keys for dev, staging, and production
Easier to rotate compromised keys
Better audit trail in logs

Rotating Keys

Rotate API keys regularly for security:

Create New Key

Generate a new API key in the dashboard with the same name + date:

production-api-2024-01

Update Applications

Deploy the new key to your applications one environment at a time:

Staging first
Test thoroughly
Then production

Monitor Usage

Verify the old key shows zero usage after migration

Revoke Old Key

Delete the old key once you’ve confirmed the new key works

Set a calendar reminder to rotate keys every 90 days.

Revoking Keys

Revoke compromised keys immediately:

Go to Settings → API Keys
Find the compromised key
Click Delete or Revoke
Generate a new key to replace it

When to revoke:

✅ Key accidentally committed to GitHub
✅ Key shared via insecure channel
✅ Employee with access leaves
✅ Suspected unauthorized access
✅ Compliance requirements

Rate Limits

API key requests are limited to 1,000 requests per hour per account.

Checking Your Limit

Response headers show your current rate limit status:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 1704657600

X-RateLimit-Limit: Total requests allowed per hour
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when limit resets

Handling Rate Limits

When you exceed the limit, you’ll receive a 429 error:

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

Best practices:

import time
import requests

def make_request_with_backoff(url, headers, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 429:
            retry_after = int(response.headers.get('Retry-After', 60))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        return response

    raise Exception("Max retries exceeded")

async function makeRequestWithBackoff(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, { headers });

    if (response.status === 429) {
      const retryAfter = response.headers.get('Retry-After') || 60;
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    return response;
  }

  throw new Error('Max retries exceeded');
}

Increasing Limits

Need more than 1,000 requests per hour?

Upgrade to OAuth

Get 15,000 requests/hour with OAuth 2.1

Contact Sales

Enterprise plans with custom limits

Security Best Practices

✅ Do’s

Store keys in environment variables

Never hard-code API keys in your source code:

# ✅ Good
import os
API_KEY = os.getenv("FLTR_API_KEY")

# ❌ Bad
API_KEY = "fltr_sk_abc123..."

Use different keys per environment

Separate keys for development, staging, and production:

# Development
FLTR_API_KEY=fltr_sk_dev_123...

# Production
FLTR_API_KEY=fltr_sk_prod_456...

Rotate keys regularly

Set up a key rotation schedule:

Every 90 days for production keys
After employee departures
After security incidents

Use .gitignore for .env files

Prevent accidental commits:

# .gitignore
.env
.env.local
.env.*.local

Implement key scanning

Use tools to detect leaked keys:

GitHub Secret Scanning
GitGuardian
TruffleHog
Pre-commit hooks

❌ Don’ts

Never do these things with API keys:

❌ Commit keys to version control (Git, SVN, etc.)
❌ Embed keys in client-side JavaScript
❌ Share keys via email, Slack, or chat
❌ Use the same key across multiple projects
❌ Post keys in GitHub issues or Stack Overflow
❌ Store keys in plain text files on servers

Compromised Keys

If you accidentally expose an API key:

Revoke Immediately

Go to Settings → API Keys and delete the compromised key

Generate New Key

Create a replacement key with a new name

Update Applications

Deploy the new key to all services using the old key

Audit Access

Check logs for suspicious activity with the compromised key

Notify Team

Alert your team and review security practices

Troubleshooting

Invalid API Key Error

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

Causes:

Key was revoked or deleted
Incorrect key format
Missing “Bearer” prefix
Extra whitespace in key

Solutions:

# ✅ Correct format
Authorization: Bearer fltr_sk_abc123...

# ❌ Wrong - missing "Bearer"
Authorization: fltr_sk_abc123...

# ❌ Wrong - extra colon
Authorization: Bearer: fltr_sk_abc123...

# ❌ Wrong - extra whitespace
Authorization: Bearer  fltr_sk_abc123...

Key Not Working After Creation

Wait 5-10 seconds after creating a key for it to propagate across our systems.

Multiple Keys Not Increasing Limit

Rate limits are per account, not per key. Creating multiple API keys doesn’t increase your rate limit from 1,000 requests/hour. To get higher limits, use OAuth authentication (15,000 req/hour).

Integration Examples

Zapier

URL: https://api.fltr.com/v1/mcp/query
Method: POST
Headers:
  Authorization: Bearer YOUR_API_KEY
  Content-Type: application/json
Body:
{
  "query": "{{input_text}}",
  "dataset_id": "ds_abc123",
  "limit": 5
}

GitHub Actions

name: Query FLTR

on: [push]

jobs:
  query:
    runs-on: ubuntu-latest
    steps:
      - name: Query FLTR API
        env:
          FLTR_API_KEY: ${{ secrets.FLTR_API_KEY }}
        run: |
          curl https://api.fltr.com/v1/datasets \
            -H "Authorization: Bearer $FLTR_API_KEY"

Add FLTR_API_KEY to your repository secrets.

Docker

FROM python:3.11-slim

# API key passed as build arg or runtime env var
ARG FLTR_API_KEY
ENV FLTR_API_KEY=${FLTR_API_KEY}

COPY . /app
WORKDIR /app

RUN pip install -r requirements.txt

CMD ["python", "app.py"]

Run with:

docker run -e FLTR_API_KEY=fltr_sk_abc123... my-app

FAQ

Can I use multiple API keys?

Yes, you can create multiple API keys for different services, but they all share the same 1,000 req/hour rate limit.

Do API keys expire?

No, API keys don’t expire automatically. Rotate them manually for security.

Can I restrict API key permissions?

Not yet. API keys have full access to your account. Use OAuth for scope-based permissions.

What happens to requests when I revoke a key?

All requests using that key will immediately return 401 Unauthorized errors.

Can I see usage per API key?

Currently, usage is tracked per account, not per key. Per-key analytics are coming soon.

Next Steps

Getting Started

Make your first API call with your new key

OAuth Setup

Upgrade to OAuth for higher rate limits

Rate Limits

Learn more about rate limiting

API Reference

Explore all available endpoints

Getting Started

Authentication

Integrations

Support

API Keys

API Key Authentication

Quick Start

API Key Format

Using API Keys

In HTTP Requests

Environment Variables

SDK Usage

Key Management

Creating Keys

Rotating Keys

Revoking Keys

Rate Limits

Checking Your Limit

Handling Rate Limits

Increasing Limits

Upgrade to OAuth

Contact Sales

Security Best Practices

✅ Do’s

❌ Don’ts

Compromised Keys

Troubleshooting

Invalid API Key Error

Key Not Working After Creation

Multiple Keys Not Increasing Limit

Integration Examples

Zapier

GitHub Actions

Docker

FAQ

Next Steps

Getting Started

OAuth Setup

Rate Limits

API Reference

​API Key Authentication

​Quick Start

​API Key Format

​Using API Keys

​In HTTP Requests

​Environment Variables

​SDK Usage

​Key Management

​Creating Keys

​Rotating Keys

​Revoking Keys

​Rate Limits

​Checking Your Limit

​Handling Rate Limits

​Increasing Limits

Upgrade to OAuth

Contact Sales

​Security Best Practices

​✅ Do’s

​❌ Don’ts

​Compromised Keys

​Troubleshooting

​Invalid API Key Error

​Key Not Working After Creation

​Multiple Keys Not Increasing Limit

​Integration Examples

​Zapier

​GitHub Actions

​Docker

​FAQ

​Next Steps

Getting Started

OAuth Setup

Rate Limits

API Reference

API Key Authentication

Quick Start

API Key Format

Using API Keys

In HTTP Requests

Environment Variables

SDK Usage

Key Management

Creating Keys

Rotating Keys

Revoking Keys

Rate Limits

Checking Your Limit

Handling Rate Limits

Increasing Limits

Security Best Practices

✅ Do’s

❌ Don’ts

Compromised Keys

Troubleshooting

Invalid API Key Error

Key Not Working After Creation

Multiple Keys Not Increasing Limit

Integration Examples

Zapier

GitHub Actions

Docker

FAQ

Next Steps