# Authentifizierung

> API-Anfragen mit einem API-Schlüssel oder OAuth-Zugriffstoken als Bearer-Token authentifizieren, den Scope full oder sending wählen, Schlüssel auf eine Domain beschränken und Authentifizierungsfehler behandeln.

Jede Anfrage an die Emailit-API muss im Header `Authorization` Zugangsdaten mitsenden. Diese Seite beschreibt die beiden Arten von Zugangsdaten (API-Schlüssel und OAuth-Zugriffstoken), was jeder Scope erlaubt, und alle Authentifizierungsfehler, die Sie zurückbekommen können.

## API-Schlüssel

Ein API-Schlüssel gehört zu einem Workspace, und jede Anfrage mit diesem Schlüssel wirkt auf diesen Workspace. Schlüssel sehen so aus:

```text
secret_Xq7pL2mN9vB4kR8tW1yZ6cH3jF5dS0aG
```

Also `secret_`, gefolgt von 32 Buchstaben und Ziffern. Schlüssel, die vor dem Format `secret_` erstellt wurden, haben kein Präfix und funktionieren weiterhin.

Erstellen Sie Schlüssel in der Weboberfläche unter **Email API → API Keys** oder mit [API-Schlüssel erstellen](/de/docs/api-reference/api-keys/create/). Das Secret wird nur einmal angezeigt, wenn Sie den Schlüssel erstellen oder [neu generieren](/de/docs/api-reference/api-keys/regenerate/). Speichern Sie es daher sofort. Wie Sie Schlüssel verwalten, erfahren Sie unter [API-Schlüssel](/de/docs/developers/api-keys/).

Dieselben Schlüssel dienen als SMTP-Passwort für das [SMTP-Relay](/de/docs/smtp/settings/).

## Schlüssel mit jeder Anfrage senden

Verwenden Sie das Schema `Bearer` im Header `Authorization`. Die API akzeptiert keine Schlüssel im Query-String oder im Anfrage-Body.

**cURL**

```bash
curl https://api.emailit.com/v2/domains \
  -H "Authorization: Bearer $EMAILIT_API_KEY"
```

**Node.js**

```javascript
const response = await fetch('https://api.emailit.com/v2/domains', {
  headers: { Authorization: `Bearer ${process.env.EMAILIT_API_KEY}` },
});
const domains = await response.json();
```

**Python**

```python
import os
import requests

response = requests.get(
    "https://api.emailit.com/v2/domains",
    headers={"Authorization": f"Bearer {os.environ['EMAILIT_API_KEY']}"},
)
domains = response.json()
```

Die SDKs setzen diesen Header für Sie, wenn Sie dem Client den Schlüssel übergeben.

## Scopes

Jeder Schlüssel hat einen von zwei Scopes. Sie wählen ihn beim Erstellen des Schlüssels und können ihn später nicht ändern.

| Scope | Darf aufrufen | Geeignet für |
| --- | --- | --- |
| `full` | Jeden Endpunkt der API. Das ist der Standardwert. | Backoffice-Tools, Skripte und Integrationen, die Domains, Kontakte, Vorlagen oder Webhooks verwalten. |
| `sending` | Nur die unten aufgeführten Sende-Endpunkte. | Anwendungsserver, die nur E-Mails senden. |

Ein Schlüssel mit dem Scope `sending` kann diese Endpunkte aufrufen und sonst nichts:

| Endpunkt | Beschreibung |
| --- | --- |
| `POST /emails` | [E-Mail senden](/de/docs/api-reference/emails/send/) |
| `POST /emails/{id}` | [Geplante E-Mail aktualisieren](/de/docs/api-reference/emails/update/) |
| `POST /emails/{id}/cancel` | [E-Mail stornieren](/de/docs/api-reference/emails/cancel/) |
| `POST /emails/{id}/retry` | [E-Mail erneut senden](/de/docs/api-reference/emails/retry/) |
| `POST /emails/{id}/forward` | [E-Mail weiterleiten](/de/docs/api-reference/emails/forward/) |

Zum Lesen von E-Mails (auflisten, abrufen, Roh-MIME, Body, Metadaten, Anhänge und Status) ist ein Schlüssel mit dem Scope `full` nötig. Ruft ein Schlüssel mit dem Scope `sending` einen anderen Endpunkt auf, gibt die API `403` mit `Permission denied: full` zurück (oder `Permission denied: read` bei den Lese-Endpunkten für E-Mails).

[Alle Endpunkte](/de/docs/api-reference/endpoints/) führt den Scope jedes Endpunkts auf.

## Schlüssel auf eine Domain beschränken

Ein Schlüssel mit dem Scope `sending` lässt sich zusätzlich auf eine Versanddomain festlegen. Übergeben Sie die ID der Domain als `sending_domain_id`, wenn Sie [den Schlüssel erstellen](/de/docs/api-reference/api-keys/create/). Ein beschränkter Schlüssel kann nur von Adressen dieser Domain senden. Jede andere Domain in `from` gibt `403` zurück:

```json
{
  "error": "Domain not authorized",
  "message": "API key is not authorized to send from this domain"
}
```

Domain-Beschränkungen gelten nur für Schlüssel mit dem Scope `sending`. Ein Schlüssel mit dem Scope `full` hat immer Zugriff auf alle Domains im Workspace.

## OAuth-Zugriffstoken

Apps, die im Namen eines Emailit-Nutzers handeln, etwa MCP-Clients und Integrationen von Drittanbietern, fragen nicht nach einem API-Schlüssel. Sie verwenden stattdessen OAuth 2.1: Der Nutzer meldet sich bei Emailit an, wählt die Workspaces, die die App nutzen darf (alle oder nur ausgewählte), und bestätigt den Scope `sending` oder `full`. Danach erhält die App ein Zugriffstoken. Der Nutzer kann diesen Zugriff unter [Verbundene Apps](/de/docs/account/connected-apps/) ändern oder widerrufen.

Senden Sie Zugriffstoken im selben Header wie API-Schlüssel:

```http
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…
```

Ein Zugriffstoken ist 15 Minuten gültig und wirkt auf den Standard-Workspace der Freigabe, mit dem gewährten Scope und der Rolle des Nutzers in diesem Workspace. Apps erneuern es mit dem Refresh-Token. Wie Sie eine solche App bauen, erfahren Sie unter [OAuth-Apps](/de/docs/developers/oauth-apps/).

## Authentifizierungsfehler

Die Authentifizierung läuft vor allem anderen. Diese Fehler können deshalb von jedem Endpunkt zurückkommen.

| Status | `message` oder `error` | Ursache | Lösung |
| --- | --- | --- | --- |
| `401` | `API key required` | Der Header `Authorization` fehlt oder beginnt nicht mit `Bearer `. | Senden Sie `Authorization: Bearer <key>`. |
| `401` | `Valid API key required` | Der Header hat das Präfix `Bearer`, aber kein Token. | Stellen Sie sicher, dass die Variable mit Ihrem Schlüssel nicht leer ist. |
| `401` | `Invalid API key` | Der Schlüssel existiert nicht, wurde gelöscht oder neu generiert (das alte Secret funktioniert nicht mehr), oder ein OAuth-Token ist abgelaufen. | Verwenden Sie einen aktuellen Schlüssel oder erneuern Sie das OAuth-Token. |
| `403` | `Workspace is suspended` | Der Workspace ist gesperrt. | Wenden Sie sich an den [Support](/contact/). |
| `403` | `Permission denied: full` | Ein Schlüssel mit dem Scope `sending` hat einen Endpunkt aufgerufen, der `full` erfordert. | Verwenden Sie einen Schlüssel mit dem Scope `full`. |
| `403` | `Domain not authorized` | Ein auf eine Domain beschränkter Schlüssel hat von einer anderen Domain gesendet. | Senden Sie von der Domain des Schlüssels oder verwenden Sie einen anderen Schlüssel. |
| `403` | `unverified_workspace_recipient` | Der Workspace ist noch nicht verifiziert, und ein Empfänger ist kein Mitglied des Workspaces. | Siehe [Nicht verifizierte Workspaces](#unverified-workspaces). |
| `503` | `Authentication service unavailable` | Ein vorübergehendes Problem auf unserer Seite. | Wiederholen Sie die Anfrage mit Backoff. |

**401**

```json
{
  "statusCode": 401,
  "error": "Unauthorized",
  "message": "Invalid API key"
}
```

**403 Scope**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Permission denied: full"
}
```

**403 Gesperrt**

```json
{
  "statusCode": 403,
  "error": "Forbidden",
  "message": "Workspace is suspended"
}
```

**403 Nicht verifiziert**

```json
{
  "code": "unverified_workspace_recipient",
  "error": "Workspace not verified",
  "message": "Unverified workspaces can only send to workspace members' account emails. Blocked recipient: ada@example.com.",
  "blocked_recipients": ["ada@example.com"]
}
```

## Nicht verifizierte Workspaces

Neue Workspaces sind zunächst nicht verifiziert. Bis Emailit den [Produktionszugang](/de/docs/workspaces/production-access/) genehmigt, sendet die API nur an die E-Mail-Adressen der Konten der Workspace-Mitglieder. Senden, erneutes Senden oder Weiterleiten an andere Empfänger gibt `403` mit dem Code `unverified_workspace_recipient` und der Liste `blocked_recipients` zurück, und Kampagnen lassen sich überhaupt nicht senden. Für alles andere funktionieren Ihre API-Schlüssel normal.

## Schlüssel geheim halten

Ein API-Schlüssel gewährt Zugriff auf Ihren Workspace. Behandeln Sie ihn deshalb wie ein Passwort.

- Rufen Sie die API nur von Ihrem Server auf. Legen Sie einen Schlüssel nie in Browser-JavaScript, einer mobilen App oder anderem Code ab, der auf dem Gerät einer anderen Person läuft.
- Halten Sie Schlüssel aus der Versionskontrolle heraus. Laden Sie sie aus Umgebungsvariablen oder einem Secrets-Manager.
- Erstellen Sie einen Schlüssel pro Anwendung und Umgebung und benennen Sie ihn nach dem Ort, an dem er verwendet wird. So können Sie einen Schlüssel widerrufen, ohne die anderen zu beeinträchtigen.
- Geben Sie jedem Schlüssel nur so viel Zugriff wie nötig: Für die meisten Anwendungen genügt ein Schlüssel mit dem Scope `sending`, beschränkt auf eine Domain.
- Prüfen Sie `last_used_at` unter [API-Schlüssel auflisten](/de/docs/api-reference/api-keys/list/) und löschen Sie Schlüssel, die Sie nicht mehr verwenden.
- Wenn ein Schlüssel offengelegt wurde, [generieren Sie ihn](/de/docs/api-reference/api-keys/regenerate/) sofort neu oder [löschen Sie ihn](/de/docs/api-reference/api-keys/delete/). Das alte Secret ist damit sofort ungültig.

## Siehe auch

  - [API-Schlüssel](/de/docs/developers/api-keys/): Schlüssel in der Weboberfläche erstellen, beschränken und rotieren.
  - [Fehler](/de/docs/api-reference/errors/): Alle Fehlerformate und Statuscodes.
  - [OAuth-Apps](/de/docs/developers/oauth-apps/): Nutzern erlauben, Ihre App mit ihrem Workspace zu verbinden.
  - [Produktionszugang](/de/docs/workspaces/production-access/): Workspace verifizieren lassen, um an beliebige Empfänger zu senden.

---
Quelle: https://emailit.com/de/docs/api-reference/authentication/