Unterkonten
Eine Plattform, die für ihre Kunden sendet, gibt jedem ein Unterkonto: eine eigene Oblic-Organisation mit eigenen Absendern, Vorlagen, Nachrichten und Berichten. Ihr Schlüssel handelt für sie, indem er sie benennt. Zum Verwalten der Unterkonten ist ein Owner- oder Admin-Schlüssel mit accounts:manage erforderlich.
Ein Unterkonto erstellen
- Name
name- Typ
- string
- Beschreibung
Erforderlich: der Name des Mandanten, höchstens 511 Zeichen.
- Name
externalId- Typ
- string
- Beschreibung
Erforderlich: Ihre eigene Mandanten-ID, höchstens 100 ASCII-Buchstaben, Ziffern sowie
_,.,:und-. Damit benennen Sie das Unterkonto später.
- Name
issueKey- Typ
- boolean
- Beschreibung
Ob das Unterkonto einen eigenen API-Schlüssel erhält; standardmäßig
true.
Ein Unterkonto erstellen
curl -X POST https://api.oblic.app/external/v1/accounts \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{ "name": "Asha Textiles", "externalId": "tenant-4821" }'
Antwort
{
"status": "success",
"data": {
"id": "ORG000R7ZM4Q2VXH00",
"name": "Asha Textiles",
"externalId": "tenant-4821",
"active": true,
"createdAt": "2026-10-24T09:30:00Z",
"apiKey": "obl_live_…"
},
"errors": null
}
apiKeyerscheint nur in dieser Antwort: speichern Sie ihn sofort oder erstellen Sie das Unterkonto erneut, um einen weiteren zu erhalten. Es ist ein User-Schlüssel mit den bisherigen Standardberechtigungen ohneevents:write: Er kann senden, lesen sowie Identitäten und Kontaktlisten verwalten, aber keine Routen aufrufen, die einen Owner- oder Admin-Schlüssel erfordern.- Dieselbe
externalIderneut liefert dasselbe Unterkonto, bei Bedarf wieder aktiviert und mit unverändertem Namen. Jeder Aufruf stellt einen weiteren Schlüssel aus, sofernissueKeynichtfalseist. Frühere Schlüssel bleiben gültig, ausgenommen die bei der Deaktivierung widerrufenen. - Ein Unterkonto hat keine Unterkonten: Wird beim Handeln für ein Unterkonto ein weiteres erstellt, lautet die Antwort
403 SUB_ACCOUNT_NOT_ALLOWED.
Unterkonten auflisten
Alle Unterkonten, auch deaktivierte mit active gleich false, in Erstellungsreihenfolge. Die Liste enthält niemals Schlüssel.
Ein Unterkonto deaktivieren
Deaktiviert das Unterkonto anhand seiner Oblic-id, nicht Ihrer externalId, und widerruft sofort alle seine Schlüssel. Eine erneute Erstellung mit derselben externalId aktiviert es wieder. Gehört das Unterkonto nicht zur Organisation, lautet die Antwort 404 ACCOUNT_NOT_FOUND.
Für ein Unterkonto handeln
Senden Sie X-Oblic-On-Behalf-Of mit der externalId des Unterkontos. Die Anfrage läuft für dieses Unterkonto, als wäre dessen eigener Schlüssel verwendet worden. Ihr einziger Schlüssel funktioniert für jeden Mandanten; Sie müssen keinen Schlüssel je Mandant aufbewahren.
Vom Konto eines Mandanten senden
curl -X POST https://api.oblic.app/external/v1/messages/email \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'X-Oblic-On-Behalf-Of: tenant-4821' \
-H 'Content-Type: application/json' \
-d '{ "from": "hello@ashatextiles.example", "to": ["asha@example.org"], "subject": "Welcome", "html": "<p>Welcome!</p>" }'
- Dem Unterkonto zugeordnet: E-Mails werden nur über seine eigenen Identitäten gesendet; Nachrichten, Berichte, Vorlagen und Webhooks sowie
Idempotency-Key-Werte gehören jeweils zum Unterkonto. - Ihnen zugeordnet: Das Guthaben Ihrer Organisation bezahlt seine Nachrichten, und Ihre IP-Zulassungsliste gilt für die Anfragen, die Sie für das Unterkonto stellen.
- Die Rolle Ihres Schlüssels gilt weiter; verwalten Sie Vorlagen, Webhooks oder die WhatsApp-Nummer eines Mandanten daher mit Ihrem eigenen Owner- oder Admin-Schlüssel und dem Header.
- Eine
externalIdohne aktives Unterkonto führt zu404 ACCOUNT_NOT_FOUND. - Die Webhook-Ereignisse des Unterkontos gehen an seine eigenen Endpunkte, sofern vorhanden, andernfalls an Ihre. Jedes Ereignis enthält seine
externalIdinaccount. Siehe Webhooks. - SMS-Vorlagen, die ein Unterkonto sendet, sind die von Ihnen freigegebenen. Siehe Vorlagen.