Authentication

The Financial Context API uses API key authentication to secure access to financial data. This guide covers how to obtain, use, and manage your API keys securely.

Getting Started

Obtaining an API Key

Sign up for a Financial Context API account
Verify your email address
Choose a subscription plan that fits your needs
Generate your API key from the dashboard

Create Account

Visit our signup page and create your account

Verify Email

Check your email and click the verification link

Choose Plan

Select from Free, Pro, or Enterprise plans based on your usage needs

Generate API Key

Navigate to the API Keys section in your dashboard and create a new key

API Key Authentication

Basic Usage

Include your API key in the request header:

curl -X GET "https://api.financialcontext.com/api/quote/AAPL" \
  -H "X-API-Key: your-api-key-here"

Header Format

Header Name	Value	Required
`X-API-Key`	Your API key	Yes
`Content-Type`	`application/json`	For POST/PUT requests
`User-Agent`	Your application identifier	Recommended

Implementation Examples

JavaScript/Node.js

const API_KEY = 'your-api-key-here';
const BASE_URL = 'https://api.financialcontext.com';

// Using fetch
async function getQuote(symbol) {
  const response = await fetch(`${BASE_URL}/api/quote/${symbol}`, {
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    }
  });
  
  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }
  
  return response.json();
}

// Using axios
const axios = require('axios');

const apiClient = axios.create({
  baseURL: BASE_URL,
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  }
});

// Usage
const quote = await apiClient.get('/api/quote/AAPL');
console.log(quote.data);

Python

import requests
import os

API_KEY = os.getenv('FINANCIAL_CONTEXT_API_KEY')
BASE_URL = 'https://api.financialcontext.com'

class FinancialContextClient:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = BASE_URL
        self.session = requests.Session()
        self.session.headers.update({
            'X-API-Key': api_key,
            'Content-Type': 'application/json'
        })
    
    def get_quote(self, symbol):
        response = self.session.get(f'{self.base_url}/api/quote/{symbol}')
        response.raise_for_status()
        return response.json()
    
    def get_financials(self, symbol, period='annual'):
        params = {'period': period}
        response = self.session.get(
            f'{self.base_url}/api/financials/{symbol}',
            params=params
        )
        response.raise_for_status()
        return response.json()

# Usage
client = FinancialContextClient(API_KEY)
quote = client.get_quote('AAPL')
print(f"AAPL Price: ${quote['data']['price']}")

PHP

<?php

class FinancialContextAPI {
    private $apiKey;
    private $baseUrl = 'https://api.financialcontext.com';
    
    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }
    
    private function makeRequest($endpoint, $params = []) {
        $url = $this->baseUrl . $endpoint;
        
        if (!empty($params)) {
            $url .= '?' . http_build_query($params);
        }
        
        $headers = [
            'X-API-Key: ' . $this->apiKey,
            'Content-Type: application/json'
        ];
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($httpCode !== 200) {
            throw new Exception("API request failed with status: $httpCode");
        }
        
        return json_decode($response, true);
    }
    
    public function getQuote($symbol) {
        return $this->makeRequest("/api/quote/$symbol");
    }
    
    public function getFinancials($symbol, $period = 'annual') {
        return $this->makeRequest("/api/financials/$symbol", ['period' => $period]);
    }
}

// Usage
$api = new FinancialContextAPI($_ENV['FINANCIAL_CONTEXT_API_KEY']);
$quote = $api->getQuote('AAPL');
echo "AAPL Price: $" . $quote['data']['price'];
?>

Java

import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;

public class FinancialContextClient {
    private final String apiKey;
    private final String baseUrl = "https://api.financialcontext.com";
    private final HttpClient httpClient;
    private final ObjectMapper objectMapper;
    
    public FinancialContextClient(String apiKey) {
        this.apiKey = apiKey;
        this.httpClient = HttpClient.newHttpClient();
        this.objectMapper = new ObjectMapper();
    }
    
    public QuoteResponse getQuote(String symbol) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(baseUrl + "/api/quote/" + symbol))
            .header("X-API-Key", apiKey)
            .header("Content-Type", "application/json")
            .GET()
            .build();
        
        HttpResponse<String> response = httpClient.send(
            request, HttpResponse.BodyHandlers.ofString());
        
        if (response.statusCode() != 200) {
            throw new RuntimeException("API request failed: " + response.statusCode());
        }
        
        return objectMapper.readValue(response.body(), QuoteResponse.class);
    }
}

// Usage
FinancialContextClient client = new FinancialContextClient(
    System.getenv("FINANCIAL_CONTEXT_API_KEY"));
QuoteResponse quote = client.getQuote("AAPL");
System.out.println("AAPL Price: $" + quote.getData().getPrice());

Security Best Practices

Environment Variables

Never hardcode API keys in your source code. Use environment variables:

# .env file
FINANCIAL_CONTEXT_API_KEY=your-api-key-here

# Load in your application
const apiKey = process.env.FINANCIAL_CONTEXT_API_KEY;

Key Rotation

Regular Rotation

Rotate API keys every 90 days for enhanced security

Immediate Rotation

Rotate immediately if you suspect a key has been compromised

Multiple Keys

Use different keys for development, staging, and production

Access Monitoring

Monitor API key usage in your dashboard regularly

Network Security

Always use HTTPS: All API requests must use HTTPS
IP Whitelisting: Restrict API key usage to specific IP addresses
Rate Limiting: Implement client-side rate limiting to avoid hitting limits
Request Signing: Consider implementing request signing for additional security

Error Handling

Authentication Errors

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or has been revoked",
    "details": {
      "timestamp": "2024-01-15T10:30:00Z",
      "requestId": "req_123456789"
    }
  }
}

Common Error Codes

Code	Status	Description	Solution
`MISSING_API_KEY`	401	No API key provided	Include X-API-Key header
`INVALID_API_KEY`	401	Invalid or revoked key	Check key validity
`RATE_LIMIT_EXCEEDED`	429	Too many requests	Implement rate limiting
`INSUFFICIENT_PERMISSIONS`	403	Plan doesn’t allow access	Upgrade subscription

Error Handling Implementation

class APIError extends Error {
  constructor(code, message, status) {
    super(message);
    this.code = code;
    this.status = status;
  }
}

async function makeAPIRequest(endpoint) {
  try {
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      headers: { 'X-API-Key': API_KEY }
    });
    
    if (!response.ok) {
      const errorData = await response.json();
      throw new APIError(
        errorData.error.code,
        errorData.error.message,
        response.status
      );
    }
    
    return response.json();
  } catch (error) {
    if (error instanceof APIError) {
      // Handle specific API errors
      switch (error.code) {
        case 'INVALID_API_KEY':
          console.error('Please check your API key');
          break;
        case 'RATE_LIMIT_EXCEEDED':
          console.error('Rate limit exceeded, please wait');
          break;
        default:
          console.error('API Error:', error.message);
      }
    } else {
      console.error('Network Error:', error.message);
    }
    throw error;
  }
}

Rate Limiting

Limits by Plan

Plan	Requests/Minute	Requests/Day	Concurrent Requests
Free	60	1,000	2
Pro	600	50,000	10
Enterprise	6,000	1,000,000	50

Rate Limit Headers

API responses include rate limit information:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1642262400
X-RateLimit-Window: 60

Implementing Rate Limiting

class RateLimitedClient {
  constructor(apiKey, requestsPerMinute = 60) {
    this.apiKey = apiKey;
    this.requestsPerMinute = requestsPerMinute;
    this.requests = [];
  }
  
  async makeRequest(endpoint) {
    await this.waitForRateLimit();
    
    const response = await fetch(`${BASE_URL}${endpoint}`, {
      headers: { 'X-API-Key': this.apiKey }
    });
    
    this.requests.push(Date.now());
    return response.json();
  }
  
  async waitForRateLimit() {
    const now = Date.now();
    const oneMinuteAgo = now - 60000;
    
    // Remove requests older than 1 minute
    this.requests = this.requests.filter(time => time > oneMinuteAgo);
    
    if (this.requests.length >= this.requestsPerMinute) {
      const oldestRequest = this.requests[0];
      const waitTime = 60000 - (now - oldestRequest);
      
      if (waitTime > 0) {
        await new Promise(resolve => setTimeout(resolve, waitTime));
      }
    }
  }
}

Testing Authentication

Verify API Key

# Test your API key
curl -X GET "https://api.financialcontext.com/api/quote/AAPL" \
  -H "X-API-Key: your-api-key-here" \
  -w "HTTP Status: %{http_code}\n"

Health Check Endpoint

# Check API status and authentication
curl -X GET "https://api.financialcontext.com/health" \
  -H "X-API-Key: your-api-key-here"

Keep your API keys secure and never expose them in client-side code, public repositories, or logs. If you suspect a key has been compromised, rotate it immediately.

API keys are tied to your account and subscription plan. Upgrading or downgrading your plan may affect your rate limits and available endpoints.

Get Started

API Guides

API Reference

Authentication

Authentication

Getting Started

Obtaining an API Key

API Key Authentication

Basic Usage

Header Format

Implementation Examples

JavaScript/Node.js

Python

PHP

Java

Security Best Practices

Environment Variables

Key Rotation

Regular Rotation

Immediate Rotation

Multiple Keys

Access Monitoring

Network Security

Error Handling

Authentication Errors

Common Error Codes

Error Handling Implementation

Rate Limiting

Limits by Plan

Rate Limit Headers

Implementing Rate Limiting

Testing Authentication

Verify API Key

Health Check Endpoint

Get Started

API Guides

API Reference

​Authentication

​Getting Started

​Obtaining an API Key

​API Key Authentication

​Basic Usage

​Header Format

​Implementation Examples

​JavaScript/Node.js

​Python

​PHP

​Java

​Security Best Practices

​Environment Variables

​Key Rotation

Regular Rotation

Immediate Rotation

Multiple Keys

Access Monitoring

​Network Security

​Error Handling

​Authentication Errors

​Common Error Codes

​Error Handling Implementation

​Rate Limiting

​Limits by Plan

​Rate Limit Headers

​Implementing Rate Limiting

​Testing Authentication

​Verify API Key

​Health Check Endpoint

Authentication

Getting Started

Obtaining an API Key

API Key Authentication

Basic Usage

Header Format

Implementation Examples

JavaScript/Node.js

Python

PHP

Java

Security Best Practices

Environment Variables

Key Rotation

Network Security

Error Handling

Authentication Errors

Common Error Codes

Error Handling Implementation

Rate Limiting

Limits by Plan

Rate Limit Headers

Implementing Rate Limiting

Testing Authentication

Verify API Key

Health Check Endpoint