認証
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:send | SMS 送信と SMS アカウント・ヘッダー・テンプレートの参照 |
whatsapp:send | WhatsApp 送信と番号・テンプレート・受信者の参照 |
messages:read | メッセージの一覧、各結果とレポート概要の参照 |
templates:manage | メールテンプレート、SMS ヘッダー・テンプレート、WhatsApp 番号・テンプレートの管理 |
identities:manage | 送信者 ID の管理 |
contacts:manage | 連絡先リストの作成・一覧取得と連絡先の追加 |
events:write | 注文など連絡先のイベントの記録(イベントを参照) |
webhooks:manage | Webhook と失敗した配信の管理 |
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 が認識したアドレスが示されます。そのアドレスを追加してください。サブアカウントへのリクエストにも組織のリストが適用されます。
キーの確認
どのキーも自身の名前、役割、スコープ、現在可能な操作を確認できます。
応答の一部
{
"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 | 条件 |
|---|---|---|
| 401 | MISSING_API_KEY | Authorization: Bearer ヘッダーがない |
| 401 | INVALID_API_KEY | 誤記・削除などにより Oblic に認識されないキー |
| 403 | IP_NOT_ALLOWED | 有効なキーだが送信元が IP 許可リスト外 |
| 403 | INSUFFICIENT_SCOPE | ルートに必要なスコープがない。メッセージと WWW-Authenticate ヘッダーが必要なものを示す |
| 403 | ROLE_NOT_ALLOWED | User キーで /external/v1/health にアクセス、または全スコープを持つ User キーで Owner・Admin 専用ルートにアクセス |
| 404 | ACCOUNT_NOT_FOUND | X-Oblic-On-Behalf-Of が有効なサブアカウントを示していない |
| 503 | AUTHENTICATION_UNAVAILABLE | 一時的にキーを確認できなかった。何も実行していないため再試行する |
キーの保護
- アプリケーションと環境ごとに別のキーを作り、必要なスコープだけを付けます。漏えい時の影響を限定し、削除で停止する対象を一つにできます。
- キーはサーバーに保存し、コード、ログ、ブラウザーやアプリがダウンロードするものに含めません。
- ローテーションでは新しいキーを作成・配備してから古いキーを削除します。削除したキーは直ちに使えなくなります。