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.


POST/external/v1/accounts

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
}
  • apiKey erscheint 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 ohne events:write: Er kann senden, lesen sowie Identitäten und Kontaktlisten verwalten, aber keine Routen aufrufen, die einen Owner- oder Admin-Schlüssel erfordern.
  • Dieselbe externalId erneut liefert dasselbe Unterkonto, bei Bedarf wieder aktiviert und mit unverändertem Namen. Jeder Aufruf stellt einen weiteren Schlüssel aus, sofern issueKey nicht false ist. 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.

GET/external/v1/accounts

Unterkonten auflisten

Alle Unterkonten, auch deaktivierte mit active gleich false, in Erstellungsreihenfolge. Die Liste enthält niemals Schlüssel.


DELETE/external/v1/accounts/{accountId}

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 externalId ohne aktives Unterkonto führt zu 404 ACCOUNT_NOT_FOUND.
  • Die Webhook-Ereignisse des Unterkontos gehen an seine eigenen Endpunkte, sofern vorhanden, andernfalls an Ihre. Jedes Ereignis enthält seine externalId in account. Siehe Webhooks.
  • SMS-Vorlagen, die ein Unterkonto sendet, sind die von Ihnen freigegebenen. Siehe Vorlagen.
War diese Seite hilfreich?