API認可
認証済みのどのAPIエンドポイントも、必ず認可を受ける必要があります。この認可は、APIキーやOAuthトークンなどの提供された認証情報に、必要なAPIスコープが少なくとも1つ含まれているかどうかを検証することによって行われます。なお、必要に応じて、APIキーにスコープを割り当てることも可能です。
APIのスコープ
スコープは、API環境において標準的な用語となっています。これはOAuth2 仕様で生まれた概念であり、同様の考え方があらゆる認証タイプに適用されています。これはエンドポイントユーザー、APIキーまたはOAuthクライアントが呼び出すことができる範囲を制限する、REST APIに対する追加の制御とセキュリティの層です。
スコープは、特定のAPIエンドポイント群へのアクセスを提供し、通常は特定のユースケースに対応するように設計されています。スコープはOAuth2を通じて、アプリケーションがユーザーに代わって実行が許可される具体的なアクションを定義します。
特定のAPIスコープをユーザーまたはAPIキーに付与することで、そのスコープの対象となるAPIエンドポイントのサブセットのみにアクセスを制限できます。これにより、ユーザーが自身のロールの権限範囲外のデータやAPI機能にアクセスすることを防ぐことができます。また、APIキーやユーザー資格情報の漏洩・盗難による潜在的な悪影響を最小限に抑えることも可能です。さらに、同じユーザーやAPIキーに対して複数のスコープを付与することで、複雑なユースケースに必要な様々なAPIエンドポイントをアクセス可能範囲に含めることもできます。
APIスコープの種類 [#api-scope-types-api-scopes]
地域や状況に応じて、様々な種類のスコープが存在します。主なスコープとしては、次のようなものが含まれます：
-
一般的なスコープ：
- message:send
- チャネルに関係なく、モバイル終端 (MT) メッセージの送信を可能にします。
- すべて (全チャネル) の
channel:message:sendエンドポイントが含まれます。
- inbound-message:read
- チャネルに関係なく、モバイル発信 (MO) メッセージをフェッチできるようにします。
- すべて (全チャネル) の
channel:inbound-message:readエンドポイントが含まれます。
- web:sdk
- クライアント側のSDKから、PeopleとPeopleイベント用APIのエンドポイントにアクセスできるようにします。
- mobile-app-messaging:sdk
- クライアント側のSDKから、モバイルアプリでメッセージングに使用されるプッシュ通知用APIのエンドポイントにアクセスできるようにします。
- message:send
-
product/channel:manage
- 特定の製品またはチャネルに関連するすべてのエンドポイントが含まれます。例えば、製品がConversationsである場合、Conversationsに関連するすべてのエンドポイントが含まれます。同様にチャネルがSMSである場合は、SMSに関連するすべてのエンドポイントが含まれます。
さらに、チャネルや製品、利用シーンによって異なる種類のスコープも存在します。利用可能なすべてのスコープについては、API キーの作成 について詳述しているページでご確認いただけます。
APIスコープの構成 [#api-scope-configuration-api-scopes]
APIのスコープを構成するには、使用する各 API エンドポイントへのアクセスを APIキー に許可する必要があります。これを行うには、まず API エンドポイントのドキュメントを確認します。必要なスコープが一覧表示されます。これらのいずれかを付与すると、APIキー がエンドポイントにアクセスできるようになります。
既存の APIキー を編集して新しいスコープを付与するか、最初からスコープを使用して新しいスコープを作成できます。
API キーは、 専用 API または Web インターフェイスを使用して管理できます。
Web インターフェイスを使用してAPIスコープを構成する場合は、[開発者ツール] → [API キー] → [APIキーの作成] に移動します。
そこから、APIキー に関する次の情報を入力します。
- 名前
- 作成日
- 有効期限
- 許可された IP アドレス (オプション)
次のセクション「APIスコープ」で、含めるスコープを選択します。
- 全般
- チャネル
- 接続
- プラットホーム
- 顧客エンゲージメント
- Web SDK
特定のスコープオプションを選択すると、使用可能なすべてのスコープを含むドロップダウンメニューが表示されます。そこから、APIキーに含めるスコープを選択する必要があります。
使用可能な API スコープ [#available-api-scopes-api-scopes]
次の表は、API プラットフォームで現在使用されているスコープの概要を示しています。
ユーザー ロールと API スコープ [#user-roles-and-api-scopes-api-scopes]
重要
APIキー を使用して NTT CPaaS HTTP API にアクセスすることをお勧めします。API スコープを詳細に制御し、他の多くのセキュリティも提供します 顔立ち。詳細については、こちらを参照してください。
APIキー を使用できず、基本認証に依存する必要がある場合は、API エンドポイントの呼び出しに使用しているパスワードを持つユーザーに、それらのエンドポイントにアクセスするために必要なスコープが付与されていることを確認する必要があります。API キーとは異なり、スコープはユーザーに直接割り当てられません。
代わりに、ユーザーにロールを割り当てると、それらのロールによって特定のスコープが暗黙的に付与されます。
特定のロールによって暗黙的に付与されるスコープについては、以下のリストを参照してください。
| Role | Scopes |
|---|---|
| Communication Manager | 2fa:pin:manage, calls:media:manage, viber-bm:manage, campaign-tags:manage, rcs:manage, callrouting:manage, omni-failover:logs:read, zalo:manage, number-lookup:logs:read, voice-message:logs:read, ivr:manage, mobile-app-messaging:manage, numbermasking:manage, forms:read, google-bm:manage, instagram:logs:read, email:logs:read, sms:manage, kakao:logs:read, messages-api:manage, signals:manage, forms:manage, viber-bot:manage, 2fa:manage, calls:manage, mms:manage, calls:recording:delete, webrtc:manage, knowledge-base:manage, forms:use, omni-failover:manage, rcs:logs:read, messenger:logs:read, inbound-message:read, viber-bot:logs:read, calls:traffic:record, flow:manage, campaign-tags:view, kakao:manage, google-bm:logs:read, calls:recording:read, web-push:manage, clicktocall:manage, number-activation-state:read, calllink:link:manage, calllink:configuration:manage, blocklist:manage, numbers:manage, apple-mfb:logs:read, voice:recording:delete, viber-bm:logs:read, whatsapp:manage, whatsapp:logs:read, voice:recording:read, message:send, voice-reports:read, flow:read, voice-message:manage, people:manage, conversations:manage, instagram:manage, live-chat:manage, mms:logs:read, metrics:manage, calls:configuration:manage, email:manage, zalo-follower:manage, calls:bulk:manage, rbm-maap:manage, voice:logs:read, number-lookup:manage, numbers:recording:manage, calls:logs:read, line:manage, content-messages:read, catalogs:manage, sending-strategy:manage, sms:logs:read, zalo:logs:read, answers:manage, calllink:manage, apple-mfb:manage, people:read, ivr:configuration:manage, voice:recording:manage, messenger:manage |
| People Manager | people:manage, conversations:manage, people:read, account-management:manage, forms:manage, mobile-app-messaging:manage, blocklist:manage |
| Analyze Manager | calls:media:manage, google-bm:logs:read, calls:recording:read, account-management:manage, omni-failover:logs:read, number-lookup:logs:read, whatsapp:inbound-message:read, voice-message:logs:read, mms:inbound-message:read, numbermasking:manage, instagram:logs:read, email:logs:read, apple-mfb:logs:read, kakao:logs:read, voice:recording:delete, viber-bm:logs:read, whatsapp:logs:read, voice:recording:read, voice-reports:read, flow:read, calls:recording:delete, forms:use, people:manage, conversations:manage, rcs:logs:read, mms:logs:read, messenger:logs:read, metrics:manage, calls:read, inbound-message:read, sms:inbound-message:read, voice:logs:read, numbers:recording:manage, viber-bot:logs:read, calls:logs:read, calls:traffic:record, answers:manage, sms:logs:read, zalo:logs:read, people:read, voice:recording:manage |
| Finance Data Manager | forms:use, numbers:manage, conversations:manage, billing:usage:view, account-management:manage |
| Account Manager | viber-bm:manage, campaign-tags:manage, rcs:manage, number-lookup:send, zalo:manage, number-lookup:logs:read, whatsapp:inbound-message:read, resource-request-hub:read, voice-message:logs:read, ivr:manage, mobile-app-messaging:manage, resource-request-hub:manage, sms:message:send, forms:read, instagram:logs:read, email:logs:read, sms:manage, kakao:logs:read, messages-api:manage, answers:testing, tiktok:manage, viber-bot:manage, flow:use, calls:manage, knowledge-base:manage, saas:tiktok-ads:manage, onboarding:manage, forms:use, rbm-maap:message:send, catalogs:use, omni-failover:message:send, messenger:logs:read, calls:traffic:receive, viber-bm:message:send, inbound-message:read, voice-message:message:send, viber-bot:logs:read, number-risk-score:manage, 2fa:pin:send, web:tracking:sdk, line:message:send, calls:traffic:record, google-bm:message:send, flow:manage, tiktok:message:send, subscriptions:manage, google-bm:logs:read, mobile-app-messaging:send, calls:recording:read, account-management:manage, web-push:manage, clicktocall:manage, blocklist:manage, ai:agents:query, billing:usage:view, apple-mfb:logs:read, whatsapp:manage, whatsapp:logs:read, email:templates:manage, people:manage, conversations:manage, 2fa:sdk, metrics:manage, calls:traffic:send, calls:configuration:manage, zalo-follower:manage, voice:logs:read, number-lookup:manage, numbers:recording:manage, kakao:message:send, saas:integrations:manage, email:message:send, zalo-follower:logs:read, line:manage, catalogs:manage, catalogs:read, audit-logs:read, mobile-app-messaging:inbound-message:read, sending-strategy:manage, apple-mfb:message:send, sms:logs:read, answers:manage, calllink:manage, apple-mfb:manage, whatsapp:message:send, ivr:configuration:manage, ai:agents:manage, voice:recording:manage, 2fa:pin:manage, calls:media:manage, callrouting:manage, knowledge-base:read, omni-failover:logs:read, webrtc:identity:manage, tiktok:logs:read, mobile-app-messaging:logs:read, mms:message:send, numbermasking:manage, google-bm:manage, viber-bot:message:send, signals:manage, people:use, forms:manage, mobile-identity:manage, 2fa:manage, mms:manage, ai:agents:view, calls:recording:delete, webrtc:manage, webrtc:media:manage, omni-failover:manage, rcs:logs:read, calls:read, markuplanguage:manage, sms:inbound-message:read, messages-api:message:send, partner-tools:access, ivr:message:send, whatsapp:conversions, web-push:send, messenger:message:send, campaign-tags:view, insights:read, rcs:provision, kakao:manage, conversations:read, number-activation-state:read, calllink:link:manage, calllink:configuration:manage, mms:inbound-message:read, numbers:manage, ai:read, application-entity:manage, voice:recording:delete, viber-bm:logs:read, voice:recording:read, zalo:message:send, message:send, webrtc:configuration:manage, voice-reports:read, flow:read, content-messages:manage, voice-message:manage, zalo-follower:message:send, instagram:manage, live-chat:manage, mms:logs:read, email:manage, calls:bulk:manage, rbm-maap:manage, instagram:message:send, calls:logs:read, content-messages:read, zalo:logs:read, flow:control, people:read, web:sdk, rcs:message:send, messenger:manage, error-codes:read, biometrics:manage |
| Integrations Manager | viber-bm:manage, campaign-tags:manage, rcs:manage, number-lookup:send, zalo:manage, number-lookup:logs:read, whatsapp:inbound-message:read, resource-request-hub:read, voice-message:logs:read, ivr:manage, mobile-app-messaging:manage, resource-request-hub:manage, sms:message:send, forms:read, instagram:logs:read, email:logs:read, sms:manage, kakao:logs:read, messages-api:manage, answers:testing, tiktok:manage, viber-bot:manage, flow:use, calls:manage, knowledge-base:manage, saas:tiktok-ads:manage, onboarding:manage, forms:use, rbm-maap:message:send, catalogs:use, omni-failover:message:send, messenger:logs:read, calls:traffic:receive, viber-bm:message:send, inbound-message:read, voice-message:message:send, viber-bot:logs:read, number-risk-score:manage, 2fa:pin:send, web:tracking:sdk, line:message:send, calls:traffic:record, google-bm:message:send, flow:manage, tiktok:message:send, subscriptions:manage, google-bm:logs:read, mobile-app-messaging:send, calls:recording:read, account-management:manage, web-push:manage, clicktocall:manage, blocklist:manage, ai:agents:query, billing:usage:view, apple-mfb:logs:read, whatsapp:manage, whatsapp:logs:read, email:templates:manage, people:manage, conversations:manage, 2fa:sdk, metrics:manage, calls:traffic:send, calls:configuration:manage, zalo-follower:manage, voice:logs:read, number-lookup:manage, numbers:recording:manage, kakao:message:send, saas:integrations:manage, email:message:send, zalo-follower:logs:read, line:manage, catalogs:manage, catalogs:read, audit-logs:read, mobile-app-messaging:inbound-message:read, sending-strategy:manage, apple-mfb:message:send, sms:logs:read, answers:manage, calllink:manage, apple-mfb:manage, whatsapp:message:send, ivr:configuration:manage, ai:agents:manage, voice:recording:manage, 2fa:pin:manage, calls:media:manage, callrouting:manage, knowledge-base:read, omni-failover:logs:read, webrtc:identity:manage, tiktok:logs:read, mobile-app-messaging:logs:read, mms:message:send, numbermasking:manage, google-bm:manage, viber-bot:message:send, signals:manage, people:use, forms:manage, mobile-identity:manage, 2fa:manage, mms:manage, ai:agents:view, calls:recording:delete, webrtc:manage, webrtc:media:manage, omni-failover:manage, rcs:logs:read, calls:read, markuplanguage:manage, sms:inbound-message:read, messages-api:message:send, partner-tools:access, ivr:message:send, whatsapp:conversions, web-push:send, messenger:message:send, campaign-tags:view, insights:read, rcs:provision, kakao:manage, conversations:read, number-activation-state:read, calllink:link:manage, calllink:configuration:manage, mms:inbound-message:read, numbers:manage, ai:read, application-entity:manage, voice:recording:delete, viber-bm:logs:read, voice:recording:read, zalo:message:send, message:send, webrtc:configuration:manage, voice-reports:read, flow:read, content-messages:manage, voice-message:manage, zalo-follower:message:send, instagram:manage, live-chat:manage, mms:logs:read, email:manage, calls:bulk:manage, rbm-maap:manage, instagram:message:send, calls:logs:read, content-messages:read, zalo:logs:read, flow:control, people:read, web:sdk, rcs:message:send, messenger:manage, error-codes:read, biometrics:manage |
| Conversations Agent | conversations:manage, content-messages:read, calls:manage, forms:manage |
| Conversations Manager | conversations:manage, content-messages:read, catalogs:manage, calls:manage, forms:manage, content-messages:manage |
| Conversations Analyze Manager | conversations:manage |
| Conversations Account Manager | conversations:manage, account-management:manage |
| Answers Manager | google-bm:logs:read, rcs:logs:read, live-chat:manage, mms:logs:read, messenger:logs:read, omni-failover:logs:read, number-lookup:logs:read, voice:logs:read, viber-bot:logs:read, voice-message:logs:read, instagram:logs:read, calls:logs:read, email:logs:read, catalogs:manage, apple-mfb:logs:read, kakao:logs:read, viber-bm:logs:read, whatsapp:logs:read, answers:manage, sms:logs:read, zalo:logs:read |
| Answers Designer | instagram:logs:read, calls:logs:read, email:logs:read, google-bm:logs:read, rcs:logs:read, catalogs:manage, apple-mfb:logs:read, kakao:logs:read, mms:logs:read, viber-bm:logs:read, whatsapp:logs:read, messenger:logs:read, zalo:logs:read, answers:manage, sms:logs:read, omni-failover:logs:read, number-lookup:logs:read, voice:logs:read, viber-bot:logs:read, voice-message:logs:read |
| Answers Supervisor | answers:manage |
| Knowledge Base Manager | conversations:manage, knowledge-base:manage |
| Knowledge Base User | conversations:manage, knowledge-base:manage |
| Campaign Content Creator | instagram:logs:read, calls:logs:read, email:logs:read, google-bm:logs:read, rcs:logs:read, apple-mfb:logs:read, kakao:logs:read, mms:logs:read, viber-bm:logs:read, whatsapp:logs:read, messenger:logs:read, zalo:logs:read, sms:logs:read, omni-failover:logs:read, number-lookup:logs:read, voice:logs:read, viber-bot:logs:read, voice-message:logs:read |
| Campaign Approval Manager | instagram:logs:read, calls:logs:read, email:logs:read, google-bm:logs:read, rcs:logs:read, apple-mfb:logs:read, kakao:logs:read, mms:logs:read, viber-bm:logs:read, whatsapp:logs:read, messenger:logs:read, zalo:logs:read, sms:logs:read, omni-failover:logs:read, number-lookup:logs:read, voice:logs:read, viber-bot:logs:read, voice-message:logs:read |
| Content Manager | campaign-tags:view, conversations:manage, content-messages:read, content-messages:manage |
エラー
指定されたユーザーまたは APIキーに必要なスコープがない場合、応答で 403 Forbidden HTTP ステータス コードを受け取ります。
json
1
2 {
3 "requestError": {
4 "serviceException": {
5 "messageId": "FORBIDDEN",
6 "text": "Forbidden"
7 }
8 }
9 }
ライブラリの例外 [#library-exceptions-errors]
ライブラリのいずれかを使用する場合は、必ずAPI例外を処理してください。
REQUEST SAMPLES
java
1
2 try {
3 SmsResponse smsResponse = sendSmsApi.sendSmsMessage(smsMessageRequest);
4 } catch (ApiException apiException) {
5 apiException.getCode();
6 apiException.getResponseHeaders();
7 apiException.getResponseBody();
8 }
csharp
1
2 try
3 {
4 var result = api.SendSmsMessage(smsRequest);
5 }
6 catch(ApiException apiException)
7 {
8 var errorCode = apiException.ErrorCode;
9 var errorContent = apiException.ErrorContent;
10 }