Authentication

All requests to Felo API Platform APIs require authentication using an API Key. This guide explains how to authenticate your requests and handle common authentication issues.

API Key Authentication

Felo uses API Key authentication for all v2 endpoints. Your API Key identifies your application and provides access to the platform's capabilities.

How It Works

1. You obtain an API Key from the Felo API Platform API Keys page
2. You include the API Key in the Authorization header of every API request
3. The platform validates your API Key and processes your request

Header Format

Include your API Key in the Authorization header using the Bearer authentication scheme:

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X POST https://openapi.felo.ai/v2/chat \
  -H "Authorization: Bearer sk_live_abc123xyz789" \
  -H "Content-Type: application/json" \
  -d '{"query": "What is machine learning?"}'

Obtaining Your API Key

To get your API Key:

1. Open the Felo API Platform API Keys page
2. Sign in with your Felo account if prompted
3. Enter a key name and click Create Key
4. Copy the full key when it appears. It is only shown once
5. Store the key securely and use it as FELO_API_KEY

Security Best Practices

1. Store API Keys Securely

Don't hardcode API Keys in your source code:

# ❌ Bad - API Key exposed in code
api_key = "sk_live_abc123xyz789"

Do use environment variables or secure configuration:

# ✅ Good - API Key from environment
import os
api_key = os.environ.get('FELO_API_KEY')

2. Use Environment Variables

Store your API Key in environment variables:

Linux/macOS:

export FELO_API_KEY="sk_live_abc123xyz789"

Windows (Command Prompt):

set FELO_API_KEY=sk_live_abc123xyz789

Windows (PowerShell):

$env:FELO_API_KEY="sk_live_abc123xyz789"

3. Rotate Keys Regularly

Periodically generate new API Keys and revoke old ones to minimize security risks.

4. Use Different Keys for Different Environments

Create separate API Keys for development, staging, and production environments.

5. Never Expose Keys in Client-Side Code

API Keys should only be used in server-side code. Never include them in:

• Frontend JavaScript code
• Mobile app source code
• Public repositories
• Client-side configuration files

Authentication Errors

Common Error Codes

Error Response Format

When authentication fails, you'll receive an error response:

{
  "status": "error",
  "code": "INVALID_API_KEY",
  "message": "The provided API Key is invalid or has been revoked",
  "request_id": "req_abc123"
}

Troubleshooting

Issue: "INVALID_API_KEY" Error

Possible causes:

• The API Key is incorrect or has typos
• The API Key has been revoked
• You're using a test key in production (or vice versa)

Solutions:

1. Double-check your API Key for typos
2. Verify the key has not been revoked on the API Keys page
3. Ensure you're using the correct key for your environment
4. Generate a new API Key if needed

Issue: "MISSING_AUTHORIZATION" Error

Possible causes:

• The Authorization header is not included in the request
• The header name is misspelled

Solutions:

1. Ensure you're including the Authorization header
2. Check the header name is exactly Authorization (case-sensitive)
3. Verify your HTTP client is sending the header correctly

Issue: "MALFORMED_AUTHORIZATION" Error

Possible causes:

• The Authorization header format is incorrect
• Missing "Bearer" prefix
• Extra spaces or characters

Solutions:

1. Use the exact format: Authorization: Bearer YOUR_API_KEY
2. Ensure there's exactly one space after "Bearer"
3. Don't include quotes around the API Key

Example: Debugging Authentication

import requests

url = "https://openapi.felo.ai/v2/chat"
api_key = "YOUR_API_KEY"

# Correct format
headers = {
    "Authorization": f"Bearer {api_key}",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers, json={"query": "test"})

if response.status_code == 401:
    error = response.json()
    print(f"Authentication failed: {error['code']}")
    print(f"Message: {error['message']}")
    print(f"Request ID: {error['request_id']}")
else:
    print("Authentication successful!")

Rate Limiting

Rate limits are enforced per endpoint, not globally per API Key. See each endpoint's documentation for whether limits apply.

Currently rate-limited:

• `/v2/chat` - limited on per-API-Key, per-user (minute window) and per-user (hourly window) dimensions. Exact numeric thresholds are read from response headers (see below) so they can be tuned without doc updates.

Other /v2/** endpoints currently have no enforced rate limits.

When a limit is exceeded, the API returns 429 Too Many Requests with X-RateLimit-* headers and Retry-After. Always read effective limits from the response headers, not from this document.

Need Help?

If you're experiencing authentication issues:

1. Review this guide carefully
2. Check the Getting Started guide
3. Verify your API Key on the API Keys page
4. Contact support at [email protected] with your request ID

Next Steps

• Getting Started Guide - Learn how to make your first API call
• Chat API Reference - Explore the Chat API documentation