API Keys Management

API keys are used to authenticate your requests to the Binom.Router API. This guide explains how to create, configure, and securely manage your API keys.

What is an API Key?

An API key is a unique identifier that authenticates your requests to Binom.Router. It serves as your digital credential when making API calls.

Key Features

• Authentication: Verifies your identity to the API
• Access Control: Determines which models and features you can access
• Rate Limiting: Controls how many requests you can make
• Security: Can be restricted to specific IP addresses
• Monitoring: Tracks usage and billing for specific applications

API Key Format

API keys follow this format:

binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

This key should be included in the Authorization header of your API requests:

Authorization: Bearer binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Creating an API Key

Step 1: Navigate to API Keys Page

1. Log in to your Binom.Router account
2. Click on "API Keys" in the main menu or navigate to /keys

Step 2: Create New Key

1. Click the "Create New API Key" button
2. A form will appear with configuration options
3. Fill in the required information
4. Click "Create API Key"

Step 3: Copy Your Key

IMPORTANT: You will only see your API key once! After this screen, the key will be hidden for security reasons.

1. Click the "Copy to Clipboard" button
2. Store the key in a secure location immediately
3. Click "I've saved my key" to dismiss the dialog

API Key Configuration Options

When creating or editing an API key, you can configure the following options:

1. Description

A human-readable label to help you identify what this key is used for.

Example values:

• My Production App
• Mobile App - iOS
• Testing Key
• Staging Environment

Best Practices:

• Be descriptive and specific
• Include the environment (dev/staging/prod)
• Include the platform or application name

2. Rate Limit

Controls the maximum number of API requests allowed per minute (RPM) for this key.

Options:

• Off: No rate limiting (uses account default)
• Custom: Set a specific value (e.g., 60, 100, 1000)

How it works:

• The counter resets every minute
• Requests exceeding the limit return HTTP 429 (Too Many Requests)
• Each key has its own independent rate limit

Recommendations:

• Development: 10-60 RPM
• Mobile App: 100-500 RPM
• Web Application: 500-2000 RPM
• Enterprise: Custom limits (contact support)

3. IP Restrictions

Restricts API key usage to specific IP addresses or IP ranges.

Format:

• Single IP: 192.168.1.1
• Multiple IPs (comma-separated): 192.168.1.1, 10.0.0.1
• CIDR ranges: 192.168.1.0/24

How it works:

• Only requests from whitelisted IPs are accepted
• Requests from other IPs return HTTP 403 (Forbidden)
• IPv4 and IPv6 addresses are supported

When to use:

• Production: Always enable IP restrictions
• Development: Optional (use dynamic DNS if needed)
• Mobile Apps: Not recommended (IP addresses change frequently)

Example configurations:

# Single server
203.0.113.45

# Multiple servers
203.0.113.45, 203.0.113.46, 203.0.113.47

# Entire subnet
203.0.113.0/24

# IPv6
2001:db8::1

4. Model Access

Restricts which AI models this API key can access.

Available models include:

• OpenAI: gpt-4, gpt-4-turbo, gpt-3.5-turbo
• Google: gemini-pro, gemini-pro-vision
• Anthropic: claude-3-opus, claude-3-sonnet, claude-3-haiku
• And more...

Configuration options:

• All Models: No restrictions (access to all models you're subscribed to)
• Selected Models: Choose specific models from a dropdown list

Benefits:

• Cost Control: Prevent accidental use of expensive models
• Application Isolation: Different keys for different use cases
• Compliance: Restrict to approved models only

Example scenarios:

# Chatbot key (text-only)
- gpt-4-turbo
- claude-3-sonnet

# Image generation key
- dall-e-3
- stable-diffusion-xl

# Cost-effective key
- gpt-3.5-turbo
- gemini-pro

5. Expires At

Sets an expiration date for the API key.

Options:

• Never: Key does not expire (default)
• Specific Date: Choose a date from the calendar picker

Behavior:

• Expired keys return HTTP 401 (Unauthorized)
• You can extend expiration before the key expires
• You cannot use expired keys after expiration

Recommendations:

• Temporary Access: Set expiration for short-term projects
• Production Keys: Use "Never" but rotate periodically
• Testing Keys: Set short expiration (1-7 days)

6. Is Enabled

Toggles the active status of the API key.

States:

• Enabled: Key can be used for API requests
• Disabled: Key is temporarily disabled (returns HTTP 401)

When to disable:

• Temporary suspension without deletion
• Debugging issues
• Planned maintenance
• Suspicious activity detected

Using Your API Key

Authorization Header

Include your API key in the Authorization header using the Bearer token scheme:

POST /v1/chat/completions HTTP/1.1
Host: api.binom-router.com
Authorization: Bearer binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Python Example

import openai

client = openai.OpenAI(
    api_key="binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    base_url="https://api.binom-router.com/v1"
)

response = client.chat.completions.create(
    model="gpt-4-turbo",
    messages=[{"role": "user", "content": "Hello!"}]
)

cURL Example

curl -X POST https://api.binom-router.com/v1/chat/completions \
  -H "Authorization: Bearer binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4-turbo",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

JavaScript/Node.js Example

import OpenAI from 'openai';

const client = new OpenAI({
  apiKey: 'binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
  baseURL: 'https://api.binom-router.com/v1'
});

const response = await client.chat.completions.create({
  model: 'gpt-4-turbo',
  messages: [{ role: 'user', content: 'Hello!' }]
});

Managing API Keys

Viewing Your Keys

Navigate to /keys to see all your API keys. The table displays:

• Description: Label you provided
• Created At: When the key was created
• Last Used: When the key was last used (if ever)
• Status: Enabled/Disabled
• Expires At: Expiration date (if set)

Editing a Key

1. Click the "Edit" button (pencil icon) next to a key
2. Modify the configuration options
3. Click "Save Changes"

Note: You cannot edit the key itself (the secret string). To change the key, delete and recreate it.

Disabling a Key

1. Click the "Edit" button
2. Toggle "Is Enabled" to off
3. Click "Save Changes"

Deleting a Key

1. Click the "Delete" button (trash icon) next to a key
2. Confirm the deletion in the dialog

Warning: Deleting a key is permanent. Any applications using this key will immediately stop working.

Viewing Usage Statistics

1. Click on a key in the list
2. View detailed usage statistics including:
   • Total requests
   • Total cost
   • Requests by model
   • Error rate
   • Timeline graph

Security Best Practices

1. Never Commit API Keys to Version Control

❌ DON'T:

# Hardcoded in code
API_KEY = "binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# In git
git commit -m "Add API key"

✅ DO:

# Use environment variables
import os
API_KEY = os.getenv("BINOM_API_KEY")

# Add to .gitignore
echo ".env" >> .gitignore

2. Use Environment Variables

Store API keys in environment variables, not in code:

# .env file
BINOM_API_KEY=binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Or set directly in terminal
export BINOM_API_KEY=binom_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

3. Implement Key Rotation

Regularly rotate your API keys:

1. Frequency: Every 30-90 days for production keys
2. Process:
   • Create a new key
   • Update your applications to use the new key
   • Test thoroughly
   • Delete the old key after confirming everything works

4. Use Separate Keys for Different Environments

• Development: Separate keys with low limits
• Staging: Separate keys with moderate limits
• Production: Separate keys with IP restrictions

5. Implement IP Restrictions

Always enable IP restrictions for production keys to prevent unauthorized usage even if the key is compromised.

6. Monitor Usage Regularly

Check your API key usage statistics:

• Look for unusual spikes in requests
• Monitor for requests from unexpected regions
• Set up alerts for suspicious activity

7. Use Minimal Required Permissions

Configure each key with the minimum necessary access:

• Only allow models you actually use
• Set reasonable rate limits
• Don't give keys more permissions than needed

8. Secure Storage

If you must store API keys (e.g., for automated processes):

• Use secret management services (AWS Secrets Manager, Azure Key Vault)
• Encrypt keys at rest
• Restrict access to secrets
• Audit access logs

9. Implement Backoff Strategy

Handle rate limits gracefully:

import time
from openai import RateLimitError

max_retries = 3
retry_delay = 1  # seconds

for attempt in range(max_retries):
    try:
        response = client.chat.completions.create(...)
        break
    except RateLimitError:
        if attempt < max_retries - 1:
            time.sleep(retry_delay * (2 ** attempt))  # Exponential backoff
        else:
            raise

Troubleshooting

HTTP 401 Unauthorized

Cause: Invalid or missing API key

Solutions:

1. Verify the key is included in the Authorization header
2. Check for typos in the key
3. Ensure the key hasn't been revoked or expired
4. Confirm the key is enabled (not disabled)

HTTP 403 Forbidden

Cause: IP restriction violation

Solutions:

1. Check your current IP address
2. Verify your IP is in the allowed list
3. Update IP restrictions if needed
4. For mobile apps, consider removing IP restrictions

HTTP 429 Too Many Requests

Cause: Rate limit exceeded

Solutions:

1. Implement exponential backoff in your code
2. Reduce request frequency
3. Increase the rate limit for this key
4. Use multiple keys for high-volume applications

Key Not Working After Creation

Possible causes:

1. You didn't copy the key (only shown once)
2. Key was accidentally disabled
3. IP restrictions are blocking your requests
4. Rate limit is set too low

Solutions:

1. Create a new key if you lost it
2. Check key status in the dashboard
3. Review IP restrictions
4. Adjust rate limit settings

Suspicious Activity Detected

If you notice unusual API usage:

1. Immediate action: Disable the compromised key
2. Investigate: Check usage logs for patterns
3. Rotate: Create a new key
4. Update: Update all applications with the new key
5. Delete: Delete the old key
6. Report: Contact support if needed