API v2 mit OAuth
Die neue Oblic-API-Version verwendet die in Oblic sichtbaren Journeys, Segmente und Nachrichten des Arbeitsbereichs, den eine Person verbindet. Sie nutzt OAuth-2.1-Zugriffstokens statt API-Schlüsseln und handelt mit der Rolle dieser Person. /external/v1 funktioniert weiterhin mit Ihren API-Schlüsseln.
Das OpenAPI-Dokument dieser Version ist external-v2.json; die OpenAPI-Referenz zeigt es als Version 2.
Token anfordern
API v2 akzeptiert niemals einen API-Schlüssel: Ein solcher Aufruf ergibt 401 API_KEY_NOT_ACCEPTED. Stattdessen verbindet eine Person Ihre Anwendung mit einem ihrer Arbeitsbereiche, in dem sie in deren Namen handelt.
Die Oblic-Bereitstellung benötigt einen aktivierten OAuth-Autorisierungsserver, API v2 als zugelassene Ressource, konfigurierte Signaturschlüssel und Einwilligungsseite sowie Ihren registrierten Client. Bestätigen Sie die Verfügbarkeit vor der Integration beim Oblic-Support; Beispiel-URLs belegen keine konfigurierte Bereitstellung.
- Registrieren Sie Ihre Anwendung. Teilen Sie dem Oblic-Support Namen, Weiterleitungs-URIs und benötigte Berechtigungsbereiche mit, um eine Client-ID zu erhalten. Clients sind öffentlich: Es gibt kein Client-Geheimnis, und jede Autorisierung nutzt PKCE. Nur Server oder native Anwendungen können die API verwenden: Weder Token-Endpunkt noch API erlauben einen Browser-Ursprung.
- Lassen Sie die Person sich anmelden. Öffnen Sie den Autorisierungsendpunkt mit der API-v2-
resourceundscope=read sendzum Senden oderscope=readnur zum Lesen. Die Person meldet sich bei Oblic an, wählt den Arbeitsbereich und genehmigt die Berechtigungsbereiche. - Tauschen Sie den Code am Token-Endpunkt mit derselben
resourceaus. - Rufen Sie die API mit
Authorization: Bearer <access token>auf.
| Autorisierungsserver | https://api.oblic.app (Metadaten unter /.well-known/oauth-authorization-server) |
| Autorisierungsendpunkt | https://api.oblic.app/oauth2/authorize |
| Token-Endpunkt | https://api.oblic.app/oauth2/token |
| Ressource | https://api.oblic.app/external/v2 |
| PKCE | Nur S256 |
| Zugriffstoken | standardmäßig eine Stunde gültig |
| Aktualisierungstoken | bei jeder Verwendung ersetzt; standardmäßig nach 30 Tagen ohne Verwendung und 90 Tagen nach der ursprünglichen Verbindung ungültig |
Code austauschen
curl -X POST https://api.oblic.app/oauth2/token \
-d grant_type=authorization_code \
-d client_id=YOUR_CLIENT_ID \
-d code=THE_CODE \
-d redirect_uri=https://app.example.com/callback \
-d code_verifier=YOUR_CODE_VERIFIER \
-d resource=https://api.oblic.app/external/v2
Ein für eine andere Ressource ausgestelltes Token, etwa den Oblic-MCP-Server, funktioniert hier nicht. Ohne nutzbares Token lautet die Antwort 401; der Header WWW-Authenticate verweist auf die Ressourcenmetadaten unter https://api.oblic.app/.well-known/oauth-protected-resource/external/v2.
Berechtigungsbereiche und Rollen
- Name
read- Typ
- scope
- Beschreibung
Fordern Sie diesen Bereich immer an: Ein Token ohne ihn wird abgewiesen. Er erlaubt das Lesen der Journeys und Segmente des Arbeitsbereichs sowie der über die API gesendeten Nachrichten.
- Name
send- Typ
- scope
- Beschreibung
Erlaubt, E-Mail-, SMS- und WhatsApp-Sendungen für die Organisation einzureihen; das bedeutet keine Zustellung durch den Anbieter. Dieser Bereich wird vor der Zustimmung in einer eigenen Zeile angezeigt.
Ein Berechtigungsbereich geht nie über die bei jeder Anfrage geprüfte Rolle hinaus. Wird die Rolle oder die Organisationsmitgliedschaft entzogen, endet der Zugriff des Tokens sofort.
- Journeys und Segmente gehören zum gewählten Arbeitsbereich; jede dortige Rolle darf sie lesen.
- Nachrichten über die API gehören wie bei einem API-Schlüssel zum Standardarbeitsbereich der Organisation. Senden erfordert
sendund die Rolle Owner, Admin oder Editor in diesem Bereich; zum Lesen genügt jede dortige Rolle.
Das Token unterliegt nicht der IP-Zulassungsliste der Organisation für API-Schlüssel: Es wird auf den Servern Ihrer Anwendung verwendet und durch die Rolle der Person und die genehmigten Berechtigungsbereiche begrenzt.
API-Endpunkte
Jede Antwort enthält {"status": "success", "data": …, "errors": null} oder "status": "error" mit den Fehlern.
| Methode | Pfad | Funktion |
|---|---|---|
GET | /external/v2/journeys | Kampagnen, Automatisierungen, WhatsApp-Bots und in Journeys erstellte Journeys des Arbeitsbereichs, zuletzt geändert zuerst |
GET | /external/v2/journeys/{id} | Eine Journey |
GET | /external/v2/segments | Listen des Arbeitsbereichs, danach seine dynamischen Segmente |
GET | /external/v2/segments/{id} | Ein Segment |
POST | /external/v2/messages/email | Sendet eine E-Mail von einem verifizierten Absender |
POST | /external/v2/messages/sms | Sendet eine zu einer Ihrer DLT-Vorlagen passende SMS |
POST | /external/v2/messages/whatsapp | Sendet eine genehmigte WhatsApp-Vorlage oder eine Antwort innerhalb von 24 Stunden |
GET | /external/v2/messages | Über die API gesendete Nachrichten, neueste zuerst, mit den Parametern der v1-Liste |
GET | /external/v2/messages/{messageId} | Eine über die API gesendete Nachricht und ihr Ergebnis |
Journeys auflisten
- Name
offset- Typ
- integer
- Beschreibung
Beginn der Seite; standardmäßig
0.
- Name
limit- Typ
- integer
- Beschreibung
Anzahl der Journeys, von 1 bis 100; standardmäßig
50.
- Name
mode- Typ
- string
- Beschreibung
campaign,automation,botoderjourneyfür eine in Journeys erstellte Journey.
- Name
status- Typ
- string
- Beschreibung
Zulässige Zustände:
draft,scheduled,live,pausedoderdone.
- Name
search- Typ
- string
- Beschreibung
Teil des Namens einer Journey.
nextOffset bezeichnet den Beginn der nächsten Seite und ist auf der letzten null.
Journeys auflisten
curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN'
Antwort
{
"status": "success",
"data": {
"journeys": [
{
"id": "CMP000R7ZM4Q2VXH00",
"mode": "campaign",
"name": "Weekly offer",
"status": "live",
"createdAt": "2026-10-01T09:30:00Z",
"updatedAt": "2026-10-12T14:05:00Z"
}
],
"nextOffset": null
},
"errors": null
}
Nachricht senden
Die Nutzdaten entsprechen /external/v1/messages. Ein Sendewunsch wird eingereiht und mit 202 und der Nachrichten-ID beantwortet. Wiederholen Sie ihn mit demselben 1 bis 255 Zeichen langen Idempotency-Key wie bei v1-Sendungen: Derselbe Sendewunsch liefert die erste ID ohne erneutes Senden; derselbe Schlüssel mit anderer Nachricht ergibt 409 IDEMPOTENCY_CONFLICT. Der Schlüssel gehört Ihrer Anwendung: Eine andere Anwendung oder ein API-Schlüssel mit demselben Wert sendet eine eigene Nachricht.
E-Mail senden
curl -X POST https://api.oblic.app/external/v2/messages/email \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
-H 'Content-Type: application/json' \
-H 'Idempotency-Key: order-4471-shipped' \
-d '{
"to": ["customer@example.com"],
"subject": "Your order has shipped",
"html": "<p>Your order 4471 is on its way.</p>"
}'
Antwort
{
"status": "success",
"data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
"errors": null
}
Lesen Sie das Ergebnis mit GET /external/v2/messages/{messageId}.
API-Fehler
| HTTP-Status | Fehlercode | Bedeutung |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | Kein Zugriffstoken gesendet |
| 401 | INVALID_ACCESS_TOKEN | Token abgelaufen, für andere Ressource ausgestellt, ohne read oder Person nicht mehr Mitglied: aktualisieren oder erneut verbinden |
| 401 | API_KEY_NOT_ACCEPTED | API-Schlüssel gesendet: mit /external/v1 verwenden |
| 403 | INSUFFICIENT_SCOPE | Benötigter Berechtigungsbereich fehlt, benannt in WWW-Authenticate: erneut verbinden und genehmigen |
| 403 | FORBIDDEN | Die Rolle der Person erlaubt diese Aktion nicht |
| 403 | EMAIL_SUSPENDED | E-Mail des Kontos wegen Rückläufern oder Spam-Beschwerden gesperrt, wie bei /external/v1 |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | Parameter, Header oder Nutzdaten fehlen oder sind unlesbar |
| 400 | Feldname, etwa TO | Ein Feld der Nutzdaten ist ungültig |
| 402 | INSUFFICIENT_BALANCE | Marketing-SMS oder -WhatsApp benötigen Guthaben im zahlenden Wallet; ein leeres Wallet verweigert keine Anmeldecodes, Transaktionsnachrichten oder Antworten |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | Nicht im Arbeitsbereich oder nicht über die API gesendet |
| 404 | NOT_FOUND | Diese Route existiert nicht |
| 405 | METHOD_NOT_ALLOWED | Die Route unterstützt die Methode nicht; Allow nennt die zulässigen Methoden |
| 415 | UNSUPPORTED_MEDIA_TYPE | Nutzdaten nicht als application/json gesendet |
| 422 | UNVERIFIED_SENDER | E-Mail-Absender nicht verifiziert |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | Stundenlimit oder Monatskontingent für E-Mail überschritten, wie bei /external/v1; Retry-After nennt den nächsten Versuch |
Auch SMS oder WhatsApp können wie bei /external/v1 mit einer konkreten Ursache abgewiesen werden: nicht genehmigte Vorlage, vom Marketing abgemeldete Nummer, nicht verbundene Nummer oder erreichtes Limit, mit Retry-After, wenn ein späterer Versuch sinnvoll ist.