> ## Documentation Index
> Fetch the complete documentation index at: https://docs.famulor.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication Guide

> Complete guide to API authentication for developers

# Authentication for Developers

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

<Info>
  For a quick reference, see our [basic authentication page](/en/api-reference/authentication) in the API reference.
</Info>

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

<Steps>
  <Step title="Open Dashboard">
    Log in to your Famulor account at [https://app.famulor.de](https://app.famulor.de)
  </Step>

  <Step title="API Keys Page">
    Navigate to the **"API Keys"** page in your dashboard
  </Step>

  <Step title="Create Key">
    Click **"Create new API key"**
  </Step>

  <Step title="Save Securely">
    Copy the key immediately and store it securely — it will only be shown once
  </Step>
</Steps>

<Warning>
  **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
</Warning>

## Using the API Key

### Standard Authentication

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

```
Authorization: Bearer YOUR_API_KEY
```

### Code Examples

<CodeGroup>
  ```javascript JavaScript/Node.js theme={null}
  // 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();
  ```

  ```python Python theme={null}
  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 PHP theme={null}
  <?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);
  ?>
  ```

  ```bash cURL theme={null}
  # 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"
  ```
</CodeGroup>

## Setting Up Environment Variables

### Local (.env file)

```bash theme={null}
# .env file
FAMULOR_API_KEY=your_actual_api_key_here
```

### Production Deployment

<CodeGroup>
  ```bash Heroku theme={null}
  heroku config:set FAMULOR_API_KEY=your_actual_api_key_here
  ```

  ```bash Vercel theme={null}
  vercel env add FAMULOR_API_KEY
  ```

  ```bash AWS Lambda theme={null}
  # In AWS Console: Environment Variables
  FAMULOR_API_KEY=your_actual_api_key_here
  ```

  ```bash Docker theme={null}
  docker run -e FAMULOR_API_KEY=your_actual_api_key_here your-app
  ```
</CodeGroup>

## Authentication Error Handling

### Common Errors and Solutions

<AccordionGroup>
  <Accordion title="401 Unauthorized - Invalid API Key">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="403 Forbidden - Insufficient Permissions">
    ```json theme={null}
    {
      "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
  </Accordion>

  <Accordion title="Missing Authorization Header">
    ```json theme={null}
    {
      "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
  </Accordion>
</AccordionGroup>

## Testing Authentication

### Simple Test Call

```bash theme={null}
curl -X GET "https://app.famulor.de/api/user/assistants" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"
```

### Expected Response

```json theme={null}
{
  "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

```http theme={null}
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200
```

### Rate Limit Exceeded

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

## Next Steps

<CardGroup cols={2}>
  <Card title="Make Your First Call" icon="phone" href="/en/api-reference/calls/make">
    Learn how to implement API calls for voice agents
  </Card>

  <Card title="Webhook Integration" icon="link" href="/en/api-reference/webhooks/post-call">
    Set up post-call data processing
  </Card>

  <Card title="Automation Platform" icon="wand-magic-sparkles" href="/en/automation-platform/introduction">
    No-code alternative to direct API use
  </Card>

  <Card title="API Reference" icon="book" href="/en/api-reference/introduction">
    Complete API documentation
  </Card>
</CardGroup>

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