認証

Oblic API の各呼び出しには、Oblic の設定で役割と必要なスコープを指定して作成した API キーを付けます。キーは組織の IP 許可リスト内のアドレスに制限できます。API v2 は代わりに OAuth アクセストークンを使います。

キーの作成

Oblic の設定 → APIの統合でキーを作成します。名前、役割(Owner、Admin、User)とアプリケーションに必要な権限スコープを指定します。キーの表示は作成時の一度だけです。シークレット管理サービスや保護された環境変数に保存してください。紛失したキーは再表示できません。別のキーを作成し、紛失したものを削除します。

キーの送信

Authorization ヘッダーに、Bearer、空白一文字、キーの順で送信します。

キー付きの呼び出し

curl https://api.oblic.app/external/v1/key \
  -H 'Authorization: Bearer YOUR_API_KEY'

API はサーバー向けで、ブラウザーからのクロスオリジンリクエストには応答しません。誰でも読めるウェブページやアプリにキーを含める必要はありません。

権限スコープ

キーには作成時のスコープが保持されます。各ルートが受け付けるスコープのうち一つでもあれば呼び出せます。スコープ導入前のキーは、連絡先のイベントを記録する events:write 以外をすべて持ちます。イベントを送る場合は、このスコープを持つキーを作成してください。

スコープ許可される操作
email:sendメール送信と使用するメールテンプレート・送信者 ID の参照
sms:sendSMS 送信と SMS アカウント・ヘッダー・テンプレートの参照
whatsapp:sendWhatsApp 送信と番号・テンプレート・受信者の参照
messages:readメッセージの一覧、各結果とレポート概要の参照
templates:manageメールテンプレート、SMS ヘッダー・テンプレート、WhatsApp 番号・テンプレートの管理
identities:manage送信者 ID の管理
contacts:manage連絡先リストの作成・一覧取得と連絡先の追加
events:write注文など連絡先のイベントの記録(イベントを参照)
webhooks:manageWebhook と失敗した配信の管理
accounts:manageサブアカウントの管理

mcp:read と mcp:write は Oblic の MCP サーバー用で、この API 用ではありません。エンドポイントとOpenAPI ドキュメントの x-oblic-scopes に各ルートのスコープが示されています。

役割

スコープにかかわらず、キーの役割によって呼び出せるルートが決まります。

  • Owner と Admin のキーはすべてのルートを呼び出せます。
  • User のキーは、テンプレート・SMS ヘッダー・WhatsApp 番号の変更、Webhook・サブアカウントの管理、/external/v1/health の確認以外のルートを呼び出せます。User キーに templates:manage、webhooks:manage、accounts:manage は指定できません。導入前のキーやサブアカウントのキーなど全スコープを持つものは、これらを一覧表示しても使えません。

これらのルートに User キーでアクセスすると、必要なスコープがない場合は 403 INSUFFICIENT_SCOPE になります。403 ROLE_NOT_ALLOWED になるのは、スコープ不要の /external/v1/health にアクセスする場合や、キーが全スコープを持つ場合です。

IP 許可リスト

設定 → APIの統合 → ホワイトリストに登録されたIPにサーバーの送信元を登録します。単一の IPv4・IPv6 や 203.0.113.0/24 のような範囲を指定できます。空なら任意のアドレスから使えますが、一件でも登録するとリスト内だけに制限されます。変更は一分以内に反映されます。

リスト外からのリクエストは 403 IP_NOT_ALLOWED となり、メッセージに Oblic が認識したアドレスが示されます。そのアドレスを追加してください。サブアカウントへのリクエストにも組織のリストが適用されます。

GET/external/v1/key

キーの確認

どのキーも自身の名前、役割、スコープ、現在可能な操作を確認できます。

応答の一部

{
  "status": "success",
  "data": {
    "name": "Order service",
    "role": "USER",
    "scopes": ["email:send", "messages:read"],
    "allScopes": false,
    "organizationId": "ORG000R7ZM4Q2VXH00",
    "capabilities": {
      "scopes": [
        { "scope": "email:send", "action": "send email", "ownerOnly": false, "granted": true, "ready": true }
      ],
      "verifiedSenders": [{ "identity": "example.com", "type": "Domain", "status": "verified" }],
      "unverifiedSenders": [],
      "defaultSender": "hello@example.com",
      "allowedIps": ["203.0.113.0/24"],
      "subAccount": false
    }
  },
  "errors": null
}

capabilities は各スコープをキーが使えるか(granted)、組織が準備できているか(ready)を示します。例えばメール送信には確認済みの送信者が必要です。準備できていない理由は reason に示されます。

拒否されたリクエスト

ステータスcd条件
401MISSING_API_KEYAuthorization: Bearer ヘッダーがない
401INVALID_API_KEY誤記・削除などにより Oblic に認識されないキー
403IP_NOT_ALLOWED有効なキーだが送信元が IP 許可リスト外
403INSUFFICIENT_SCOPEルートに必要なスコープがない。メッセージと WWW-Authenticate ヘッダーが必要なものを示す
403ROLE_NOT_ALLOWEDUser キーで /external/v1/health にアクセス、または全スコープを持つ User キーで Owner・Admin 専用ルートにアクセス
404ACCOUNT_NOT_FOUNDX-Oblic-On-Behalf-Of が有効なサブアカウントを示していない
503AUTHENTICATION_UNAVAILABLE一時的にキーを確認できなかった。何も実行していないため再試行する

キーの保護

  • アプリケーションと環境ごとに別のキーを作り、必要なスコープだけを付けます。漏えい時の影響を限定し、削除で停止する対象を一つにできます。
  • キーはサーバーに保存し、コード、ログ、ブラウザーやアプリがダウンロードするものに含めません。
  • ローテーションでは新しいキーを作成・配備してから古いキーを削除します。削除したキーは直ちに使えなくなります。
このページは役に立ちましたか?