Skip to content
Last updated

🔐 Authentication

Learn how to securely authenticate with the Freddy API using API keys and manage your authentication workflow.

🔑 API Key Authentication

Freddy uses API key authentication for all requests. Your API key identifies your account and provides access to your resources.

Getting Your API Key

  1. Log in to the Freddy Hub
  2. Navigate to Settings → API Keys
  3. Click "Create New API Key"
  4. Name your key (e.g., "Production App", "Development")
  5. Copy the key immediately (it won't be shown again)

API Key Format

All Freddy API keys follow this format:

ak_1234567890abcdef1234567890abcdef12345678
  • Prefix: ak_ (identifies it as an API key)
  • Length: 42 characters total
  • Characters: Alphanumeric (a-z, A-Z, 0-9)

🔒 Using Your API Key

Include your API key in the api-key header:

curl -X GET "https://api.freddy.ai/v2/models" \
  -H "api-key: ak_your_api_key_here" \
  -H "Content-Type: application/json"

Code Examples

Python

import requests

# Set up authentication
api_key = "ak_your_api_key_here"
headers = {
    "api-key": api_key,
    "Content-Type": "application/json"
}

# Make authenticated request
response = requests.get(
    "https://api.freddy.ai/v2/models",
    headers=headers
)

if response.status_code == 200:
    print("Success:", response.json())
else:
    print("Error:", response.status_code, response.text)

JavaScript/Node.js

const apiKey = "ak_your_api_key_here";

const headers = {
  "api-key": apiKey,
  "Content-Type": "application/json"
};

fetch("https://api.freddy.ai/v2/models", {
  method: "GET",
  headers: headers
})
  .then(response => {
    if (!response.ok) {
      throw new Error(`HTTP error! status: ${response.status}`);
    }
    return response.json();
  })
  .then(data => console.log("Success:", data))
  .catch(error => console.error("Error:", error));

PHP

<?php
$api_key = "ak_your_api_key_here";
$url = "https://api.freddy.ai/v2/models";

$headers = [
    "api-key: " . $api_key,
    "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);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($http_code == 200) {
    $data = json_decode($response, true);
    print_r($data);
} else {
    echo "Error: " . $http_code . " - " . $response;
}
?>

🛡️ Security Best Practices

1. Keep Your API Keys Secret

✅ DO:

  • Store API keys in environment variables
  • Use secure key management systems
  • Rotate keys regularly
  • Use different keys for different environments

❌ DON'T:

  • Commit API keys to version control
  • Share keys in chat or email
  • Use production keys in development
  • Hardcode keys in your application

2. Environment Variables

Store your API key securely:

# .env file
FREDDY_API_KEY=ak_your_api_key_here
# Python
import os
api_key = os.getenv('FREDDY_API_KEY')
// Node.js
const apiKey = process.env.FREDDY_API_KEY;

3. Key Rotation

Regularly rotate your API keys:

  1. Create a new key in the Hub
  2. Update your applications to use the new key
  3. Test thoroughly in staging environment
  4. Deploy to production
  5. Delete the old key after confirming everything works

🚨 Error Handling

Common Authentication Errors

401 Unauthorized

{
  "detail": "Invalid API key",
  "status_code": 401,
  "error_type": "AuthenticationError"
}

Causes:

  • Missing API key header
  • Invalid or expired API key
  • Malformed API key

403 Forbidden

{
  "detail": "Insufficient permissions",
  "status_code": 403,
  "error_type": "PermissionError"
}

Causes:

  • API key doesn't have required permissions
  • Account limitations or restrictions
  • Resource access denied

Error Handling Code

import requests

def make_authenticated_request(endpoint, api_key):
    headers = {"api-key": api_key}
    
    try:
        response = requests.get(f"https://api.freddy.ai/v2/{endpoint}", headers=headers)
        
        if response.status_code == 401:
            print("Authentication failed. Check your API key.")
            return None
        elif response.status_code == 403:
            print("Permission denied. Check your account permissions.")
            return None
        elif response.status_code == 200:
            return response.json()
        else:
            print(f"Unexpected error: {response.status_code}")
            return None
            
    except requests.exceptions.RequestException as e:
        print(f"Request failed: {e}")
        return None

🔄 Rate Limiting

API keys are subject to rate limits based on your plan:

  • Standard: 100 requests/minute
  • Premium: 1,000 requests/minute
  • Enterprise: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

📊 Monitoring Usage

Track your API usage in the Freddy Hub:

  1. Go to Settings → API Keys
  2. View Usage Statistics for each key
  3. Monitor Rate Limit Status
  4. Set up Usage Alerts

🆘 Troubleshooting

API Key Not Working?

  1. Check the format - Should start with ak_
  2. Verify in Hub - Ensure key exists and is active
  3. Check headers - Use api-key header name
  4. Test with cURL - Isolate the issue

Still Having Issues?

Secure authentication is the foundation of a great API experience! 🔐