Skip to main content

​
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

1

Open Dashboard

Log in to your Famulor account at https://app.famulor.de
2

API Keys Page

Navigate to the “API Keys” page in your dashboard
3

Create Key

Click “Create new API key”
4

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();

​
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

​
Authentication Error Handling

​
Common Errors and Solutions

{
  "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
{
  "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
{
  "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.