Authentication for Developers

This guide shows you how to properly authenticate your Famulor API requests while following best practices for security and troubleshooting.

For a quick reference, see our basic authentication page in the API reference.

Overview

The Famulor API uses Bearer token authentication with API keys. Every API call must include a valid API key in the Authorization header.

Getting an API Key

Open Dashboard

API Keys Page

Navigate to the “API Keys” page in your dashboard

Create Key

Click “Create new API key”

Save Securely

Copy the key immediately and store it securely — it will only be shown once

Important Security Notes:

Keep your API key confidential and secure
Never share it publicly or in code repositories
Rotate keys regularly (recommended: every 90 days)
Use environment variables to store keys

Using the API Key

Standard Authentication

Include your API key in the Authorization header of every request:

Authorization: Bearer YOUR_API_KEY

Code Examples

// Use environment variable
const API_KEY = process.env.FAMULOR_API_KEY;

const response = await fetch('https://app.famulor.de/api/user/assistants', {
  method: 'GET',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  }
});

const data = await response.json();

import os
import requests

# Use environment variable
API_KEY = os.getenv('FAMULOR_API_KEY')

headers = {
    'Authorization': f'Bearer {API_KEY}',
    'Content-Type': 'application/json'
}

response = requests.get(
    'https://app.famulor.de/api/user/assistants',
    headers=headers
)

data = response.json()

<?php
// Use environment variable
$apiKey = getenv('FAMULOR_API_KEY');

$headers = [
    'Authorization: Bearer ' . $apiKey,
    'Content-Type: application/json'
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.famulor.de/api/user/assistants');
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);
?>

# Set environment variable
export FAMULOR_API_KEY="your_actual_api_key_here"

# API call
curl -X GET "https://app.famulor.de/api/user/assistants" \
     -H "Authorization: Bearer $FAMULOR_API_KEY" \
     -H "Content-Type: application/json"

Setting Up Environment Variables

Local (.env file)

# .env file
FAMULOR_API_KEY=your_actual_api_key_here

Production Deployment

heroku config:set FAMULOR_API_KEY=your_actual_api_key_here

vercel env add FAMULOR_API_KEY

# In AWS Console: Environment Variables
FAMULOR_API_KEY=your_actual_api_key_here

docker run -e FAMULOR_API_KEY=your_actual_api_key_here your-app

Authentication Error Handling

Common Errors and Solutions

401 Unauthorized - Invalid API Key

{
  "error": "Invalid API key",
  "message": "The provided API key is invalid or expired"
}

Solutions:

Verify the API key was copied correctly
Ensure there are no leading/trailing spaces
Check if the key is still valid (not expired)
Generate a new API key if needed

403 Forbidden - Insufficient Permissions

{
  "error": "Insufficient permissions",
  "message": "Your API key does not have permission for this resource"
}

Solutions:

Check the permissions of your API key
Contact support if you need elevated permissions
Ensure you are accessing the correct resource

Missing Authorization Header

{
  "error": "Missing Authorization header",
  "message": "Authorization header is required"
}

Solutions:

Make sure the Authorization header is set
Check the spelling: Authorization: Bearer YOUR_API_KEY
Verify your HTTP client is configured to include it

Testing Authentication

Simple Test Call

curl -X GET "https://app.famulor.de/api/user/assistants" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Expected Response

{
  "assistants": [
    {
      "id": 123,
      "name": "My Assistant",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Security Best Practices

✅ Recommended Practices

Use environment variables for API keys
Use HTTPS for all API calls
Rotate keys regularly
Apply least privilege permissions
Log API calls without exposing keys

❌ Avoid

Hardcoding API keys in code
Committing keys to version control
Transmitting keys over insecure channels
Using keys in client-side JavaScript
Passing keys via URL parameters

Rate Limiting

The Famulor API implements rate limiting to protect the infrastructure:

Standard limit: 100 requests per minute
Burst limit: 20 requests per 10 seconds

Rate Limit Headers

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

Rate Limit Exceeded

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please try again later.",
  "retry_after": 60
}

Next Steps

Make Your First Call

Learn how to implement API calls for voice agents

Webhook Integration

Set up post-call data processing

Automation Platform

No-code alternative to direct API use

API Reference

Complete API documentation

Start with a simple test call to ensure your authentication works correctly before implementing more complex integrations.

For Developers API Integration Examples

​Authentication for Developers

​Overview

​Getting an API Key

​Using the API Key

​Standard Authentication

​Code Examples

​Setting Up Environment Variables

​Local (.env file)

​Production Deployment

​Authentication Error Handling

​Common Errors and Solutions

​Testing Authentication

​Simple Test Call

​Expected Response

​Security Best Practices

​✅ Recommended Practices

​❌ Avoid

​Rate Limiting

​Rate Limit Headers

​Rate Limit Exceeded

​Next Steps

Make Your First Call

Webhook Integration

Automation Platform

API Reference

Authentication for Developers

Overview

Getting an API Key

Using the API Key

Standard Authentication

Code Examples

Setting Up Environment Variables

Local (.env file)

Production Deployment

Authentication Error Handling

Common Errors and Solutions

Testing Authentication

Simple Test Call

Expected Response

Security Best Practices

✅ Recommended Practices

❌ Avoid

Rate Limiting

Rate Limit Headers

Rate Limit Exceeded

Next Steps