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.


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.

  1. 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.
  2. Lassen Sie die Person sich anmelden. Öffnen Sie den Autorisierungsendpunkt mit der API-v2-resource und scope=read send zum Senden oder scope=read nur zum Lesen. Die Person meldet sich bei Oblic an, wählt den Arbeitsbereich und genehmigt die Berechtigungsbereiche.
  3. Tauschen Sie den Code am Token-Endpunkt mit derselben resource aus.
  4. Rufen Sie die API mit Authorization: Bearer <access token> auf.
Autorisierungsserverhttps://api.oblic.app (Metadaten unter /.well-known/oauth-authorization-server)
Autorisierungsendpunkthttps://api.oblic.app/oauth2/authorize
Token-Endpunkthttps://api.oblic.app/oauth2/token
Ressourcehttps://api.oblic.app/external/v2
PKCENur S256
Zugriffstokenstandardmäßig eine Stunde gültig
Aktualisierungstokenbei 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 send und 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.

MethodePfadFunktion
GET/external/v2/journeysKampagnen, Automatisierungen, WhatsApp-Bots und in Journeys erstellte Journeys des Arbeitsbereichs, zuletzt geändert zuerst
GET/external/v2/journeys/{id}Eine Journey
GET/external/v2/segmentsListen des Arbeitsbereichs, danach seine dynamischen Segmente
GET/external/v2/segments/{id}Ein Segment
POST/external/v2/messages/emailSendet eine E-Mail von einem verifizierten Absender
POST/external/v2/messages/smsSendet eine zu einer Ihrer DLT-Vorlagen passende SMS
POST/external/v2/messages/whatsappSendet 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, bot oder journey für eine in Journeys erstellte Journey.

  • Name
    status
    Typ
    string
    Beschreibung

    Zulässige Zustände: draft, scheduled, live, paused oder done.

  • 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-StatusFehlercodeBedeutung
401MISSING_ACCESS_TOKENKein Zugriffstoken gesendet
401INVALID_ACCESS_TOKENToken abgelaufen, für andere Ressource ausgestellt, ohne read oder Person nicht mehr Mitglied: aktualisieren oder erneut verbinden
401API_KEY_NOT_ACCEPTEDAPI-Schlüssel gesendet: mit /external/v1 verwenden
403INSUFFICIENT_SCOPEBenötigter Berechtigungsbereich fehlt, benannt in WWW-Authenticate: erneut verbinden und genehmigen
403FORBIDDENDie Rolle der Person erlaubt diese Aktion nicht
403EMAIL_SUSPENDEDE-Mail des Kontos wegen Rückläufern oder Spam-Beschwerden gesperrt, wie bei /external/v1
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYParameter, Header oder Nutzdaten fehlen oder sind unlesbar
400Feldname, etwa TOEin Feld der Nutzdaten ist ungültig
402INSUFFICIENT_BALANCEMarketing-SMS oder -WhatsApp benötigen Guthaben im zahlenden Wallet; ein leeres Wallet verweigert keine Anmeldecodes, Transaktionsnachrichten oder Antworten
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDNicht im Arbeitsbereich oder nicht über die API gesendet
404NOT_FOUNDDiese Route existiert nicht
405METHOD_NOT_ALLOWEDDie Route unterstützt die Methode nicht; Allow nennt die zulässigen Methoden
415UNSUPPORTED_MEDIA_TYPENutzdaten nicht als application/json gesendet
422UNVERIFIED_SENDERE-Mail-Absender nicht verifiziert
429RATE_LIMITED, QUOTA_EXCEEDEDStundenlimit 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.

War diese Seite hilfreich?