OAuth で利用する API v2

新しい Oblic API は、ユーザーが接続したワークスペースにある、Oblic 上のジャーニー、セグメント、メッセージを扱います。API キーではなく OAuth 2.1 アクセストークンで認可され、ユーザーのロールに従います。/external/v1 は引き続き API キーで利用できます。


トークンを取得する

API v2 は API キーを受け付けません。送信すると 401 API_KEY_NOT_ACCEPTED が返ります。代わりにユーザーがアプリを自分のワークスペースに接続し、アプリがそこでユーザーに代わって操作します。

Oblic のデプロイでは OAuth 認可サーバーが有効で、API v2 が許可リソースに登録され、署名鍵と同意ページが設定され、クライアントが登録されている必要があります。統合前に Oblic サポートへ利用可否を確認してください。例示 URL はデプロイの設定済み状態を保証しません。

  1. アプリを登録します。 アプリ名、リダイレクト URI、必要なスコープを Oblic サポートに伝え、クライアント ID を取得します。クライアントはパブリックで、クライアントシークレットはなく、すべての認可で PKCE を使用します。API を使えるのはサーバーまたはネイティブアプリのみで、トークンエンドポイントと API はブラウザーオリジンを許可しません。
  2. ユーザーにログインを案内します。 API v2 を示す resource と、送信用の scope=read send または読み取り専用の scope=read を指定して認可エンドポイントを開きます。ユーザーは Oblic にログインし、ワークスペースを選択してスコープを承認します。
  3. コードを交換します。 トークンエンドポイントで同じ resource を指定します。
  4. API を呼び出します。 Authorization: Bearer <access token> を使用します。
認可サーバーhttps://api.oblic.app(メタデータは /.well-known/oauth-authorization-server)
認可エンドポイントhttps://api.oblic.app/oauth2/authorize
トークンエンドポイントhttps://api.oblic.app/oauth2/token
リソースhttps://api.oblic.app/external/v2
PKCES256 のみ
アクセストークン既定では 1 時間有効
リフレッシュトークン使用のたびに置き換えられ、既定では未使用 30 日または最初の接続から 90 日で失効

コードを交換する

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

Oblic の MCP サーバーなど、別のリソース向けのトークンは使用できません。利用可能なトークンがないリクエストは 401 と WWW-Authenticate ヘッダーを受け取ります。このヘッダーはリソースメタデータ https://api.oblic.app/.well-known/oauth-protected-resource/external/v2 を示します。

スコープとロール

  • 名前
    read
    タイプ
    scope
    説明

    必ず要求してください。このスコープのないトークンは拒否されます。ワークスペースのジャーニーとセグメント、および API 経由のメッセージを読み取れます。

  • 名前
    send
    タイプ
    scope
    説明

    組織としてメール、SMS、WhatsApp の送信をキューに入れる権限です。プロバイダーによる配信完了を意味しません。承認前に、このスコープは独立した行でユーザーに提示されます。

スコープがユーザーのロールを超えることはなく、Oblic は毎回のリクエストでロールを確認します。ロールの削除や組織からのユーザー削除により、トークンのアクセスは直ちに停止します。

  • ジャーニーとセグメントはユーザーが選んだワークスペースに属し、そのワークスペースのどのロールでも読み取れます。
  • メッセージは API キーの場合と同様、組織の既定ワークスペースに属します。送信には send と、既定ワークスペースの Owner、Admin、Editor のいずれかが必要です。読み取りには同ワークスペースの任意のロールが必要です。

トークンには、組織が API キー用に設定した IP 許可リストは適用されません。アプリのサーバーから使用され、ユーザーのロールと承認済みスコープに制限されます。


API エンドポイント

各応答は {"status": "success", "data": …, "errors": null}、または "status": "error" とエラーを返します。

メソッドパス機能
GET/external/v2/journeysワークスペースのキャンペーン、自動化、WhatsApp ボット、Journeys で作成したジャーニーを更新日時の降順で取得
GET/external/v2/journeys/{id}単一のジャーニー
GET/external/v2/segmentsワークスペースのリストと、その後に動的セグメント
GET/external/v2/segments/{id}単一のセグメント
POST/external/v2/messages/email確認済み送信者からメールを送信
POST/external/v2/messages/sms登録された DLT テンプレートに一致する SMS を送信
POST/external/v2/messages/whatsapp承認済み WhatsApp テンプレート、または 24 時間以内の返信を送信
GET/external/v2/messagesAPI 経由のメッセージを新しい順に取得し、v1 の一覧のパラメーターを使用
GET/external/v2/messages/{messageId}API 経由のメッセージとその結果

ジャーニーを一覧表示する

  • 名前
    offset
    タイプ
    integer
    説明

    ページの開始位置。既定は 0。

  • 名前
    limit
    タイプ
    integer
    説明

    ジャーニー数は 1 から 100。既定は 50。

  • 名前
    mode
    タイプ
    string
    説明

    campaign、automation、bot、または Journeys 自体で作成したものを示す journey。

  • 名前
    status
    タイプ
    string
    説明

    指定可能な状態は draft、scheduled、live、paused、done。

  • 名前
    search
    タイプ
    string
    説明

    ジャーニー名の一部。

ページの nextOffset は次ページの開始位置で、最終ページでは null です。

ジャーニーを一覧表示する

curl 'https://api.oblic.app/external/v2/journeys?status=live&limit=20' \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN'

応答

{
  "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
}

メッセージを送信する

本文は /external/v1/messages と同じです。送信はキューに入り、202 とメッセージ ID が返ります。1 から 255 文字の同じ Idempotency-Key ヘッダーで、v1 の送信と同様に安全に再試行できます。同じ送信は最初の ID を返し、再送信しません。同じキーで異なるメッセージを送ると 409 IDEMPOTENCY_CONFLICT になります。キーはアプリ固有なので、別アプリや API キーが同じ値を使う場合は別のメッセージとして送信されます。

メールを送信する

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>"
  }'

応答

{
  "status": "success",
  "data": { "id": "msg_4f9c2a7e1b8d4e0f9a6c3b2d1e0f9a8b", "status": "queued" },
  "errors": null
}

結果は GET /external/v2/messages/{messageId} で確認します。


API のエラー

HTTP ステータスエラーコード意味
401MISSING_ACCESS_TOKENアクセストークンが送信されていない
401INVALID_ACCESS_TOKEN期限切れ、別リソース向け、read がない、またはユーザーが組織を離れている。更新するか再接続する
401API_KEY_NOT_ACCEPTEDAPI キーが送信された。/external/v1 で使用する
403INSUFFICIENT_SCOPE必要なスコープがない。WWW-Authenticate に示されるスコープを再接続して承認する
403FORBIDDENユーザーのロールでは許可されない
403EMAIL_SUSPENDEDバウンスや迷惑メール報告によりアカウントのメールが停止されている。/external/v1 と同じ
400BAD_REQUEST, INVALID_IDEMPOTENCY_KEYパラメーター、ヘッダー、本文がないか読み取れない
400TO などのフィールド名本文のフィールドが無効
402INSUFFICIENT_BALANCEマーケティング SMS または WhatsApp は支払い元ウォレットの残高が必要。残高不足を理由にログインコード、トランザクションメッセージ、返信は拒否しない
404JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUNDワークスペースにないか、API 経由で送信されていない
404NOT_FOUNDそのルートがない
405METHOD_NOT_ALLOWEDリクエストのメソッドは使用できない。Allow が利用可能なメソッドを示す
415UNSUPPORTED_MEDIA_TYPE本文が application/json で送信されていない
422UNVERIFIED_SENDERメール送信者が未確認
429RATE_LIMITED, QUOTA_EXCEEDEDアカウントの時間単位制限または月間枠を超えている。/external/v1 と同様に Retry-After が再試行時刻を示す

SMS や WhatsApp も /external/v1 と同様、未承認テンプレート、マーケティング拒否済み番号、未接続番号、上限到達などの理由で拒否されます。後で再試行するとよい場合には Retry-After が付与されます。

このページは役に立ちましたか?