Authentication

Learn how to authenticate your API requests with API keys.

API Keys

All API requests require authentication using an API key. You can create and manage API keys from your dashboard.

Keep your API keys secure

Never expose API keys in client-side code or public repositories
Use environment variables to store API keys
Rotate keys periodically and immediately if compromised
Use separate keys for development and production

Using Your API Key

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

curl https://api.macroestimator.com/v1/estimate/sync \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "apple"}]}'

Environment Variables

Store your API key in an environment variable to keep it secure:

Shell

# Add to your .bashrc, .zshrc, or .env file
export MACROESTIMATOR_API_KEY="me_live_..."

# Use in curl
curl https://api.macroestimator.com/v1/estimate/sync \
  -H "Authorization: Bearer $MACROESTIMATOR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "banana"}]}'

Python

import os
import requests

api_key = os.environ.get("MACROESTIMATOR_API_KEY")
if not api_key:
    raise ValueError("MACROESTIMATOR_API_KEY environment variable not set")

response = requests.post(
    "https://api.macroestimator.com/v1/estimate/sync",
    headers={
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    },
    json={"messages": [{"role": "user", "content": "orange"}]}
)

JavaScript / Node.js

const apiKey = process.env.MACROESTIMATOR_API_KEY;
if (!apiKey) {
  throw new Error("MACROESTIMATOR_API_KEY environment variable not set");
}

const response = await fetch(
  "https://api.macroestimator.com/v1/estimate/sync",
  {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      messages: [{ role: "user", content: "avocado" }]
    })
  }
);

API Key Format

MacroEstimator API keys follow this format:

me_live_... - Production/live API key
me_test_... - Test/development API key

Rate Limits

API requests are rate limited based on your subscription plan. Rate limit information is included in response headers:

Header	Description
`X-RateLimit-Limit`	Maximum requests per time window
`X-RateLimit-Remaining`	Requests remaining in current window
`X-RateLimit-Reset`	Unix timestamp when the window resets
`Retry-After`	Seconds to wait before retrying (only when rate limited)

Handling Rate Limits

When you exceed your rate limit, the API returns a 429 Too Many Requests response. Here is how to handle it:

import time
import requests

def make_request_with_retry(api_key: str, data: dict, max_retries: int = 3):
    """Make an API request with automatic retry on rate limit."""
    url = "https://api.macroestimator.com/v1/estimate/sync"
    headers = {
        "Authorization": f"Bearer {api_key}",
        "Content-Type": "application/json"
    }

    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=data)

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

        response.raise_for_status()
        return response.json()

    raise Exception("Max retries exceeded")

Error Responses

401Unauthorized

Missing or invalid API key

{
  "error": "Invalid API key"
}

403Forbidden

API key does not have permission for this operation

{
  "error": "API key does not have access to this resource"
}

429Too Many Requests

Rate limit exceeded

{
  "error": "Rate limit exceeded"
}

Managing API Keys

You can manage your API keys from the API Keys page in your dashboard:

Create new API keys with optional labels
View usage statistics for each key
Revoke compromised or unused keys
Set key expiration dates