OAuth で利用する API v2
新しい Oblic API は、ユーザーが接続したワークスペースにある、Oblic 上のジャーニー、セグメント、メッセージを扱います。API キーではなく OAuth 2.1 アクセストークンで認可され、ユーザーのロールに従います。/external/v1 は引き続き API キーで利用できます。
このバージョンの OpenAPI ドキュメントは external-v2.json で、OpenAPI リファレンスではバージョン 2 として表示されます。
トークンを取得する
API v2 は API キーを受け付けません。送信すると 401 API_KEY_NOT_ACCEPTED が返ります。代わりにユーザーがアプリを自分のワークスペースに接続し、アプリがそこでユーザーに代わって操作します。
Oblic のデプロイでは OAuth 認可サーバーが有効で、API v2 が許可リソースに登録され、署名鍵と同意ページが設定され、クライアントが登録されている必要があります。統合前に Oblic サポートへ利用可否を確認してください。例示 URL はデプロイの設定済み状態を保証しません。
- アプリを登録します。 アプリ名、リダイレクト URI、必要なスコープを Oblic サポートに伝え、クライアント ID を取得します。クライアントはパブリックで、クライアントシークレットはなく、すべての認可で PKCE を使用します。API を使えるのはサーバーまたはネイティブアプリのみで、トークンエンドポイントと API はブラウザーオリジンを許可しません。
- ユーザーにログインを案内します。 API v2 を示す
resourceと、送信用のscope=read sendまたは読み取り専用のscope=readを指定して認可エンドポイントを開きます。ユーザーは Oblic にログインし、ワークスペースを選択してスコープを承認します。 - コードを交換します。 トークンエンドポイントで同じ
resourceを指定します。 - 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 |
| PKCE | S256 のみ |
| アクセストークン | 既定では 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/messages | API 経由のメッセージを新しい順に取得し、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 ステータス | エラーコード | 意味 |
|---|---|---|
| 401 | MISSING_ACCESS_TOKEN | アクセストークンが送信されていない |
| 401 | INVALID_ACCESS_TOKEN | 期限切れ、別リソース向け、read がない、またはユーザーが組織を離れている。更新するか再接続する |
| 401 | API_KEY_NOT_ACCEPTED | API キーが送信された。/external/v1 で使用する |
| 403 | INSUFFICIENT_SCOPE | 必要なスコープがない。WWW-Authenticate に示されるスコープを再接続して承認する |
| 403 | FORBIDDEN | ユーザーのロールでは許可されない |
| 403 | EMAIL_SUSPENDED | バウンスや迷惑メール報告によりアカウントのメールが停止されている。/external/v1 と同じ |
| 400 | BAD_REQUEST, INVALID_IDEMPOTENCY_KEY | パラメーター、ヘッダー、本文がないか読み取れない |
| 400 | TO などのフィールド名 | 本文のフィールドが無効 |
| 402 | INSUFFICIENT_BALANCE | マーケティング SMS または WhatsApp は支払い元ウォレットの残高が必要。残高不足を理由にログインコード、トランザクションメッセージ、返信は拒否しない |
| 404 | JOURNEY_NOT_FOUND, SEGMENT_NOT_FOUND, MESSAGE_NOT_FOUND | ワークスペースにないか、API 経由で送信されていない |
| 404 | NOT_FOUND | そのルートがない |
| 405 | METHOD_NOT_ALLOWED | リクエストのメソッドは使用できない。Allow が利用可能なメソッドを示す |
| 415 | UNSUPPORTED_MEDIA_TYPE | 本文が application/json で送信されていない |
| 422 | UNVERIFIED_SENDER | メール送信者が未確認 |
| 429 | RATE_LIMITED, QUOTA_EXCEEDED | アカウントの時間単位制限または月間枠を超えている。/external/v1 と同様に Retry-After が再試行時刻を示す |
SMS や WhatsApp も /external/v1 と同様、未承認テンプレート、マーケティング拒否済み番号、未接続番号、上限到達などの理由で拒否されます。後で再試行するとよい場合には Retry-After が付与されます。