---
title: API-Schlüssel
description: API-Schlüssel mit vollem oder reinem Sendezugriff erstellen, auf eine Domain oder ein Postfach beschränken und verwalten.
ai:
  exclude: true
---

Ein API-Schlüssel ist das Geheimnis, das Ihr Code bei jeder Anfrage mitsendet. Erstellen Sie einen unter **API-Schlüssel** im Dashboard oder mit der API selbst. Ein Schlüssel wird nur einmal angezeigt, beim Erstellen, speichern Sie ihn also in Ihrem Secret-Manager.

```sh
curl https://api.billionsend.com/emails \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "hello@example.com",
    "to": "success@simulator.amazonses.com",
    "subject": "Hi",
    "text": "Hello."
  }'
```

Schlüssel beginnen mit `bs_`. BillionSend speichert nur einen Hash des Schlüssels, ein verlorener Schlüssel lässt sich daher nicht erneut anzeigen: Widerrufen Sie ihn und erstellen Sie einen neuen.

## Einen Schlüssel erstellen

Öffnen Sie im Dashboard **API-Schlüssel** und wählen Sie **API-Schlüssel erstellen**. Inhaber, Admins und Entwickler können das tun; siehe [Teamrollen](/docs/de/team-roles). Wählen Sie:

- **Name**: 1 bis 80 Zeichen, damit Sie Schlüssel unterscheiden können. Sie können ihn später umbenennen.
- **Berechtigung**: **Vollzugriff** oder **Nur Versand**.
- **Domain**: **Beliebige Domain** oder eine verifizierte Domain Ihres Teams.
- **Auf ein Postfach beschränken** (erscheint, sobald Sie Postfächer haben): das eine [Postfach](/docs/de/inboxes), auf das der Schlüssel beschränkt ist.

Mit der API:

```sh
curl -X POST "https://api.billionsend.com/api-keys" \
  -H "Authorization: Bearer bs_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "permission": "sending_access",
    "domain_id": "af8ad875-319f-4df5-a359-4f2430f3e766"
  }'
```

Die Antwort ist `{ "id": "…", "token": "bs_…" }`: Das Token erscheint nur hier. `GET /api-keys` listet aktive Schlüssel auf (nie ihre Tokens), und `DELETE /api-keys/{id}` widerruft einen sofort; Anfragen mit ihm schlagen unmittelbar fehl.

## Berechtigung

| Berechtigung | Darf |
| --- | --- |
| **Vollzugriff** | Jeden Endpunkt nutzen: Versand, Kontakte, Segmente, Themen, Newsletter-Versände, Domains, Webhooks, Vorlagen, empfangene E-Mails und API-Schlüssel. Ein [auf eine Domain beschränkter](#einen-schlüssel-auf-eine-domain-beschränken) Schlüssel erreicht davon nur einen Teil. |
| **Nur Versand** | E-Mails senden (`POST /emails`, `POST /emails/batch`) und nichts sonst. Alles außerhalb des Versands und jedes Lesen gespeicherter E-Mails antwortet mit `403 restricted_api_key`. |

Verwenden Sie in der App, die Transaktionsmails sendet, einen Schlüssel mit „Nur Senden“. Ein geleakter Schlüssel mit „Nur Senden“ kann Ihre Kontakte nicht lesen, Ihre Domains nicht ändern und keine weiteren Schlüssel erstellen.

## Einen Schlüssel auf eine Domain beschränken

Ein auf eine Domain beschränkter Schlüssel arbeitet innerhalb dieser einen Domain und erreicht nichts, was zum gesamten Team gehört. Eine Domain muss verifiziert sein, bevor Sie einen Schlüssel auf sie beschränken können; die Subdomain des gemeinsamen Postfachs ist nicht nutzbar.

| Was | Was der Schlüssel darf |
| --- | --- |
| Versand, E-Mails, empfangene E-Mails, Postfächer, Abmeldungen, Newsletter-Versände | Nur die dieser Domain. Eine Anfrage für eine andere Domain antwortet mit `403 restricted_api_key`. |
| `GET /emails/metrics` | Liest nur die Zahlen dieser Domain; wird in `domain_id` eine andere Domain genannt, antwortet es mit `403 restricted_api_key`. |
| `GET /domains` und `/domains/{id}` (lesen, ändern, löschen, verifizieren) | Listet und berührt nur die eigene Domain. Jede andere Domain, auch die gemeinsame Subdomain, antwortet mit `404`. |
| `/api-keys` | `POST` erstellt Schlüssel, die auf dieselbe Domain beschränkt sind. `GET` listet und `DELETE` widerruft nur Schlüssel, die auf diese Domain beschränkt sind; jeder andere Schlüssel antwortet mit `404`. |
| Kontakte, Segmente, Themen | Erlaubt. Kontakte sind das gemeinsame Adressbuch des Teams, aber der Schlüssel kann eine teamweite Abmeldung nicht aufheben. Ein Segment oder Thema, das er anlegt, wird an seine eigene Domain gebunden, und er kann keines lösen. |
| Webhooks (jede Methode, auch das Signing-Secret), Sperrlisten, Vorlagen, Kontakteigenschaften, `GET /usage`, `GET /deliverability`, Verifizierungen und `POST /domains` | `403 restricted_api_key`: Diese gehören zum gesamten Team. |

Nutzen Sie einen solchen Schlüssel für einen Dienst, der zu einer einzelnen Marke gehört: Wenn er leakt, erreicht er die Domain dieser Marke und sonst nichts, weder Ihre Webhooks noch Ihre anderen Schlüssel oder Domains.

## Einen Schlüssel auf ein Postfach beschränken

Ein Postfach-Schlüssel gibt einem KI-Agenten Zugriff auf ein [Postfach](/docs/de/inboxes) und sonst nichts. Er braucht vollen Zugriff, lässt sich nicht zugleich auf eine Domain beschränken und kann nur für dieses Postfach lesen, antworten, weiterleiten und Entwürfe senden sowie nur von dessen Adresse senden. Er funktioniert nicht mehr, wenn das Postfach abläuft oder gelöscht wird.

## Limits

| Limit | Wert |
| --- | --- |
| Aktive Schlüssel pro Team | 25, [SMTP-Zugangsdaten](/docs/de/smtp) eingeschlossen. Widerrufen Sie einen, um einen weiteren zu erstellen (sonst `422`). |
| Aktive Schlüssel pro Postfach | 5, außerhalb der 25 des Teams. |
| Anfragen | 600 pro Minute und Schlüssel und 3.000 pro Team; siehe [API-Grundlagen](/docs/de/api-reference/basics). |

## Wer welchen Schlüssel erstellen darf

- Im Dashboard erstellen Inhaber, Admins und Entwickler Schlüssel.
- Ein Schlüssel, den Sie mit der API erstellen, ist nie umfassender als der Schlüssel, der ihn erstellt hat: Ein Schlüssel mit „Nur Senden“ kann nur Schlüssel mit „Nur Senden“ erstellen, ein auf eine Domain beschränkter Schlüssel kann nur Schlüssel für diese Domain erstellen (und sieht und widerruft nur diese), und ein Postfach-Schlüssel kann keine Schlüssel erstellen.
- Ein Schlüssel handelt mit der Teamrolle, die sein Ersteller **heute** hat, bei jeder Anfrage neu geprüft. Der Ersteller ist die Person, die ihn im Dashboard erstellt hat (oder die App verbunden hat, die ihn erstellt hat); ein über die API erstellter Schlüssel übernimmt den Ersteller des Schlüssels, der ihn erstellt hat. Die Rolle schränkt die alltägliche Arbeit nicht ein: Ein Schlüssel mit vollem Zugriff sendet und verwaltet Kontakte, Newsletter-Versände, Domains, Webhooks und Schlüssel, welche Rolle sein Ersteller auch hat (ein auf eine Domain beschränkter Schlüssel ist die Ausnahme, siehe oben). Die Aktionen mit hohem Risiko (einen Empfänger löschen, eine Sperre entfernen, eine Abmeldung zurücknehmen) erfordern einen Schlüssel, dessen Ersteller gerade Inhaber oder Admin ist; andere Schlüssel antworten mit `403 forbidden`. Wird der Ersteller herabgestuft, folgen seine Schlüssel ab der nächsten Anfrage der neuen Rolle. Wird er aus dem Team entfernt oder verlässt es, funktionieren alle API-Schlüssel, die er erstellt hat, die Schlüssel, die diese Schlüssel erstellt haben, und seine Agent-Schlüssel sofort nicht mehr (`401 invalid_api_key`) und erscheinen als widerrufen; eine erneute Einladung bringt sie nicht zurück. Siehe [Teamrollen](/docs/de/team-roles).

Das Erstellen, Umbenennen und Widerrufen eines Schlüssels wird im [Audit-Log](/docs/de/audit-log) festgehalten.

## Weitere Schlüssel

- **SMTP-Zugangsdaten** sind Schlüssel mit „Nur Senden“, die auf der Seite **SMTP** für das [SMTP-Relay](/docs/de/smtp) erstellt werden.
- **Agent-Schlüssel** (`bs_agent_…`) sind nur für den [MCP-Server](/docs/de/mcp) gedacht. Sie werden unter **MCP** erstellt, sind auf „nur lesen“, „lesen und antworten“ oder „lesen und senden“ beschränkt, und ein Team besitzt bis zu 20. Ihre regulären API-Schlüssel funktionieren auf dem MCP-Server nicht.
