Logo
CTRLK
Logo
CTRLK
無料で試す
すべての Essentials を表示
はじめに
アカウントを管理する
API の要点
API の要点
API 認証
API 認証
API サービスのステータス
ベースURL
コンテンツの種類
ENUM 統合マニュアル
インテグレーションのベストプラクティス
IP アドレスのセーフリスト
各国語シフト
応答ステータスとエラーコード
SMPP仕様
支える
LATAM登録

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]

地域や状況に応じて、様々な種類のスコープが存在します。主なスコープとしては、次のようなものが含まれます：

  1. General (全般)：

    • 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のエンドポイントにアクセスできるようにします。

  2. product/channel:manage

    • 特定の製品またはチャネルに関連するすべてのエンドポイントが含まれます。例えば、製品がConversationsである場合、Conversationsに関連するすべてのエンドポイントが含まれます。同様にチャネルがSMSである場合は、SMSに関連するすべてのエンドポイントが含まれます。

さらに、チャネルや製品、利用シーンによって異なる種類のスコープも存在します。利用可能なすべてのスコープについては、API キーの作成 について詳述しているページでご確認いただけます。

APIスコープの構成 [#api-scope-configuration-api-scopes]

APIのスコープを構成するには、使用したい各APIエンドポイントへのアクセスをAPIキーに許可する必要があります。具体的には、まずそのAPIエンドポイントについて詳述しているドキュメントをご確認ください。そこには必要なスコープが一覧表示されています。それらのいずれかを許可することで、APIキーがそのエンドポイントにアクセスできるようになります。

既存のAPIキーを編集して新しいスコープを付与することができます。あるいは、最初から許可するスコープを設定して新しいAPIキーを作成することもできます。

APIキーの管理は、専用のAPIまたはWebインターフェースのいずれかを通じて行うことができます。

Webインターフェースを通じてAPIのスコープを構成したい場合は、Developer Tools (開発者ツール) → API Keys (APIキー) → Create API key (APIキーの作成)に移動します。

そこから、APIキーに関する次の情報を入力します：

  • Name (名前)
  • Creation date (作成日)
  • Expiration date (失効日)
  • Allowed IP addresses (optional) (許可されたIPアドレス (任意))

次のセクションAPI scopes (APIスコープ) で、含めたいスコープを選択します：

  • General (全般)
  • Channels (チャネル)
  • Connectivity (接続性)
  • Platform (プラットフォーム)
  • Customer Engagement (顧客エンゲージメント)
  • Web SDK (ウェブSDK)

特定のスコープオプションを選択すると、利用可能なすべてのスコープの一覧が表示されたドロップダウンメニューが現れます。そこから、APIキーに含めたいスコープを選択する必要があります。

使用可能なAPIスコープ [#available-api-scopes-api-scopes]

次の表は、APIプラットフォームで現在使用されているスコープの概要を示しています。

ユーザーロールとAPIスコープ [#user-roles-and-api-scopes-api-scopes]

重要

NTT CPaaS HTTP APIにアクセスするには、APIキーを使用することをお勧めします。APIキーを使用すると、APIのスコープを細かく管理できるほか、その他にも数多くのセキュリティ機能を活用できます。 詳細については、こちら をご参照ください。

APIキーを使用できず、基本認証に頼らざるを得ない場合は、APIエンドポイントを呼び出す際に使用するパスワードを設定しているユーザーに対し、それらのエンドポイントにアクセスするために必要なスコープが付与されていることを確認する必要があります。APIキーとは異なり、スコープはユーザーに直接割り当てられるものではありません。

その代わりとして、ユーザーにロールを割り当てる ことが可能です。そうしたロールは暗黙的に特定のスコープを付与する仕組みになっています。

特定のロールによって暗黙的に付与されるスコープについては、以下のリストをご参照ください：

Scopes implicitly granted by roles
RoleScopes
Campaign manager2fa: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, 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
Customer profile managerpeople:manage, conversations:manage, people:read, account-management:manage, forms:manage, mobile-app-messaging:manage, blocklist:manage
Analyze managercalls: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 managerforms:use, numbers:manage, conversations:manage, billing:usage:view, account-management:manage
Account adminviber-bm:manage, campaign-tags:manage, rcs:manage, number-lookup:send, zalo:manage, branded-domains: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, voice:logs:read, number-lookup:manage, numbers:recording:manage, kakao:message:send, saas:integrations:manage, email:message:send, 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, 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, mcp:provision, voice:recording:read, zalo:message:send, message:send, webrtc:configuration:manage, voice-reports:read, flow:read, content-messages:manage, voice-message:manage, 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
Channel setup and integrationsviber-bm:manage, campaign-tags:manage, rcs:manage, number-lookup:send, zalo:manage, branded-domains: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, voice:logs:read, number-lookup:manage, numbers:recording:manage, kakao:message:send, saas:integrations:manage, email:message:send, 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, 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, mcp:provision, voice:recording:read, zalo:message:send, message:send, webrtc:configuration:manage, voice-reports:read, flow:read, content-messages:manage, voice-message:manage, 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
Agent for Conversationsconversations:manage, content-messages:read, calls:manage, forms:manage
Supervisor for Conversationsconversations:manage, content-messages:read, catalogs:manage, calls:manage, forms:manage, content-messages:manage
Analytics for Conversationsconversations:manage
Conversations setupconversations:manage, account-management:manage
Chatbot publishergoogle-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
Chatbot designerinstagram: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
Chatbots (view only)answers:manage
Knowledge base managerconversations:manage, knowledge-base:manage
Knowledge base userconversations:manage, knowledge-base:manage
Campaign content creatorinstagram: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 managerinstagram: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 managercampaign-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 }
← API 認証API サービスのステータス →

Logo

ご不明点は

サポートまでお問い合わせ

ください

© NTT DOCOMO BUSINESS X,Inc.