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

# Authentifizierungs-Leitfaden

> Vollständiger Leitfaden zur API-Authentifizierung für Entwickler

# Authentifizierung für Entwickler

Dieser Leitfaden zeigt dir, wie du deine Famulor API-Anfragen korrekt authentifizierst und dabei Best Practices für Sicherheit und Fehlerbehebung befolgst.

<Info>
  Für eine schnelle Referenz siehe unsere [grundlegende Authentifizierungsseite](/de/api-reference/authentication) in der API-Referenz.
</Info>

## Überblick

Die Famulor API verwendet **Bearer Token-Authentifizierung** mit API-Schlüsseln. Jeder API-Aufruf muss einen gültigen API-Schlüssel im `Authorization` Header enthalten.

## API-Schlüssel erhalten

<Steps>
  <Step title="Dashboard öffnen">
    Melde dich bei deinem Famulor-Konto an unter [https://app.famulor.de](https://app.famulor.de)
  </Step>

  <Step title="API-Schlüssel Seite">
    Navigiere zur **"API-Schlüssel"** Seite in deinem Dashboard
  </Step>

  <Step title="Schlüssel erstellen">
    Klicke auf **"Neuen API-Schlüssel erstellen"**
  </Step>

  <Step title="Sicher speichern">
    Kopiere den Schlüssel sofort und speichere ihn sicher ab - er wird nur einmal angezeigt
  </Step>
</Steps>

<Warning>
  **Wichtige Sicherheitshinweise:**

  * Halte deinen API-Schlüssel vertraulich und sicher
  * Teile ihn niemals öffentlich oder in Code-Repositories
  * Rotiere Schlüssel regelmäßig (empfohlen: alle 90 Tage)
  * Verwende Umgebungsvariablen für die Speicherung
</Warning>

## API-Schlüssel verwenden

### Standard-Authentifizierung

Füge deinen API-Schlüssel in den `Authorization` Header jeder Anfrage ein:

```
Authorization: Bearer YOUR_API_KEY
```

### Code-Beispiele

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

  # Umgebungsvariable verwenden
  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
  // Umgebungsvariable verwenden
  $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}
  # Umgebungsvariable setzen
  export FAMULOR_API_KEY=\"your_actual_api_key_here\"

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

## Umgebungsvariablen Setup

### Lokal (.env Datei)

```bash theme={null}
# .env Datei
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>

## Authentifizierungs-Fehlerbehandlung

### Häufige Fehler und Lösungen

<AccordionGroup>
  <Accordion title="401 Unauthorized - Ungültiger API-Schlüssel">
    ```json theme={null}
    {
      "error": "Invalid API key",
      "message": "The provided API key is invalid or expired"
    }
    ```

    **Lösungen:**

    * Überprüfe, ob der API-Schlüssel korrekt kopiert wurde
    * Stelle sicher, dass keine Leerzeichen vor/nach dem Schlüssel stehen
    * Prüfe, ob der Schlüssel noch gültig ist (nicht abgelaufen)
    * Erstelle bei Bedarf einen neuen API-Schlüssel
  </Accordion>

  <Accordion title="403 Forbidden - Fehlende Berechtigung">
    ```json theme={null}
    {
      "error": "Insufficient permissions",
      "message": "Your API key does not have permission for this resource"
    }
    ```

    **Lösungen:**

    * Überprüfe die Berechtigungen deines API-Schlüssels
    * Kontaktiere den Support, falls erweiterte Berechtigungen benötigt werden
    * Stelle sicher, dass du auf die richtige Ressource zugreifst
  </Accordion>

  <Accordion title="Missing Authorization Header">
    ```json theme={null}
    {
      "error": "Missing Authorization header",
      "message": "Authorization header is required"
    }
    ```

    **Lösungen:**

    * Stelle sicher, dass der `Authorization` Header gesetzt ist
    * Prüfe die Schreibweise: `Authorization: Bearer YOUR_API_KEY`
    * Überprüfe, ob der Header in deinem HTTP-Client korrekt konfiguriert ist
  </Accordion>
</AccordionGroup>

## Authentifizierung testen

### Einfacher Test-Aufruf

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

### Erwartete Antwort

```json theme={null}
{
  "assistants": [
    {
      "id": 123,
      "name": "Mein Assistent",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}
```

## Best Practices für Sicherheit

### ✅ Empfohlene Praktiken

* **Umgebungsvariablen** für API-Schlüssel verwenden
* **HTTPS** für alle API-Aufrufe nutzen
* **Schlüsselrotation** regelmäßig durchführen
* **Minimale Berechtigungen** anwenden
* **Logging** von API-Aufrufen ohne Schlüssel-Preisgabe

### ❌ Vermeide

* API-Schlüssel im Code hart codieren
* Schlüssel in Versionskontrollsysteme committen
* Schlüssel über unsichere Kanäle übertragen
* Schlüssel in Client-seitigem JavaScript verwenden
* Schlüssel in URL-Parametern übertragen

## Rate Limiting

Die Famulor API implementiert Rate Limiting zum Schutz der Infrastruktur:

* **Standard-Limit**: 100 Anfragen pro Minute
* **Burst-Limit**: 20 Anfragen pro 10 Sekunden

### Rate Limit Headers

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

### Rate Limit überschritten

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

## Nächste Schritte

<CardGroup cols={2}>
  <Card title="Ersten Anruf tätigen" icon="phone" href="/de/api-reference/calls/make">
    Lerne, wie du API-Aufrufe für Voice Agents implementierst
  </Card>

  <Card title="Webhook-Integration" icon="link" href="/de/api-reference/webhooks/post-call">
    Post-Call-Datenverarbeitung einrichten
  </Card>

  <Card title="Automatisierungsplattform" icon="wand-magic-sparkles" href="/de/automation-platform/introduction">
    No-Code-Alternative zur direkten API-Nutzung
  </Card>

  <Card title="API Referenz" icon="book" href="/de/api-reference/introduction">
    Vollständige API-Dokumentation
  </Card>
</CardGroup>

<Tip>
  Beginne mit einem einfachen Test-Aufruf, um sicherzustellen, dass deine Authentifizierung korrekt funktioniert, bevor du komplexere Integrationen implementierst.
</Tip>