Authentication

All FinBrain API v2 requests require authentication using your API key. The v2 API supports multiple authentication methods for flexibility and backward compatibility.

Authentication Methods

The API checks for credentials in the following order of precedence:

1. Authorization Header (Recommended)

Pass your API key as a Bearer token in the Authorization header:

Authorization: Bearer YOUR_API_KEY

This is the recommended method for all new integrations. It keeps credentials out of URLs and is compatible with standard HTTP tooling.

2. X-API-Key Header

Pass your API key in the X-API-Key header:

X-API-Key: YOUR_API_KEY

3. Query Parameter

Pass your API key as the apiKey query parameter:

https://api.finbrain.tech/v2/predictions/daily/AAPL?apiKey=YOUR_API_KEY

4. Legacy Query Parameter (v1 Backward Compatibility)

The v1 token query parameter is still supported for backward compatibility:

https://api.finbrain.tech/v2/predictions/daily/AAPL?token=YOUR_API_KEY

Caution

The token query parameter is deprecated and may be removed in a future version. Migrate to the Authorization header when possible.

Example

cURL

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/daily/AAPL"

Python (requests)

import requests

headers = {"Authorization": "Bearer YOUR_API_KEY"}

response = requests.get(
    "https://api.finbrain.tech/v2/predictions/daily/AAPL",
    headers=headers
)

data = response.json()
print(data)

JavaScript

const API_KEY = "YOUR_API_KEY";

const response = await fetch(
  "https://api.finbrain.tech/v2/predictions/daily/AAPL",
  {
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  }
);

const data = await response.json();
console.log(data);

Getting an API Key

1. Visit finbrain.tech
2. Create an account or sign in
3. Navigate to your account dashboard
4. Copy your API key

Authentication Errors

401 Unauthorized

Returned when the API key is missing or invalid.

Response:

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

Common causes:

• Missing API key in the request
• Typo in the API key
• Using an expired or revoked API key

403 Forbidden

Returned when the API key is valid but lacks permission for the requested resource.

Response:

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied for this resource"
  }
}

Common causes:

• Endpoint not included in your subscription tier
• Account suspended
• Accessing a restricted resource

429 Too Many Requests

Returned when rate limits are exceeded.

Response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please slow down."
  }
}

Rate Limiting

The v2 API includes rate limit information in every response via HTTP headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed per hour
X-RateLimit-Remaining	Requests remaining in current window
X-RateLimit-Reset	Time when rate limit resets (ISO 8601)

Example response headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-03-09T15:00:00Z

When you exceed the rate limit, the API returns a 429 Too Many Requests response. Use the X-RateLimit-Reset header to determine when you can resume making requests.

Rate Limit Tiers

Tier	Requests/Hour
Free	100
Basic	1,000
Professional	10,000
Enterprise	Custom

Security Best Practices

Environment Variables

Never hardcode your API key. Use environment variables:

Python

import os
import requests

api_key = os.environ.get("FINBRAIN_API_KEY")
headers = {"Authorization": f"Bearer {api_key}"}

response = requests.get(
    "https://api.finbrain.tech/v2/predictions/daily/AAPL",
    headers=headers
)

JavaScript

const API_KEY = process.env.FINBRAIN_API_KEY;

const response = await fetch(
  "https://api.finbrain.tech/v2/predictions/daily/AAPL",
  {
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  }
);

Bash

export FINBRAIN_API_KEY="your_api_key_here"
curl -H "Authorization: Bearer $FINBRAIN_API_KEY" \
  "https://api.finbrain.tech/v2/predictions/daily/AAPL"

.env Files

For local development, use a .env file:

.env

FINBRAIN_API_KEY=your_api_key_here

Add .env to your .gitignore:

.gitignore

.env

Production Secrets

In production, use your platform’s secrets management:

• AWS: Secrets Manager or Parameter Store
• Google Cloud: Secret Manager
• Azure: Key Vault
• Heroku: Config Vars
• Vercel: Environment Variables

Additional Security Tips

1. Never commit API keys to version control
2. Don’t expose keys in client-side code - use a backend proxy
3. Rotate keys periodically - especially after team member changes
4. Use different keys for development and production
5. Monitor usage - check for unexpected API call patterns
6. Prefer header-based auth - query parameters can leak in server logs and browser history

Related Documentation

• API Reference Overview
• Error Codes
• Quick Start