# 🔐 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](https://freddy-hub.com)
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

### Header Authentication (Recommended)

Include your API key in the `api-key` header:


```bash
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


```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


```javascript
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
<?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:


```bash
# .env file
FREDDY_API_KEY=ak_your_api_key_here
```


```python
# Python
import os
api_key = os.getenv('FREDDY_API_KEY')
```


```javascript
// 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


```json
{
  "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


```json
{
  "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


```python
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](https://freddy-hub.com):

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?

- 📖 **[Getting Started](/docs/documentation/getting-started)** - Basic setup guide
- 🔌 **[API Reference](/docs/api-reference/introduction)** - Detailed endpoint docs
- 🌐 **[Hub](https://freddy-hub.com)** - Manage your keys
- 📧 **Support** - Contact our team


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