API 認証

認証されたすべての API エンドポイントにも承認が必要です。これは、指定された資格情報 (APIキー や OAuth トークンなど) に必要な API スコープが少なくとも 1 つあるかどうかを確認することによって行われます。必要に応じて、APIキー にスコープを割り当てることができます。

API スコープ

スコープは、API 環境の標準的な用語になっています。これは OAuth2 (opens in a new tab) 仕様に由来し、すべての認証タイプに同じ考え方が適用されます。これは、エンドポイント ユーザー、APIキー、または OAuth クライアントが呼び出すことができるものを制限する、REST API API に対する制御とセキュリティの追加レイヤーです。

スコープは、通常、特定のユース ケースに対応するように設計された、特定の API エンドポイントのセットへのアクセスを提供します。OAuth2 を使用して、アプリケーションがユーザーに代わって実行できる特定のアクションを定義します。

特定のAPIスコープをユーザーまたはAPIキーに付与することで、そのスコープでカバーされるAPIエンドポイントのサブセットへのアクセスを制限します。このようにして、ユーザーが自分の役割以外のデータや API 機能にアクセスできないようにすることができます。漏洩または盗難に遭った API キーまたはユーザー認証情報による潜在的な悪影響を制限できます。同じユーザーまたは APIキーに複数のスコープを付与して、複雑なユースケースに必要な複数の異なる API エンドポイントをカバーできます。

API スコープの種類

スコープの種類は、領域やコンテキストに応じてさまざまです。主なスコープは次のとおりです。

1. 全般：

   • メッセージ:送信
     • チャネルに関係なく、モバイル終端(MT)メッセージの送信を有効にします
     • すべてのchannel:message:sendエンドポイント(すべてのチャネル)が含まれます
   • 受信メッセージ:読み取り
     • チャネルに関係なく、モバイル発信(MO)メッセージの取得を有効にします
     • すべてのchannel:inbound-message:readエンドポイント(すべてのチャネル)が含まれます
   • web:sdk (英語)
     • クライアント側の SDK からアクセスされるエンドポイントAPI PeopleイベントとPeopleイベントへのアクセスを提供します
   • モバイルアプリメッセージング:SDK
     • クライアント側の SDK からアクセスされるモバイルアプリメッセージングモバイルプッシュ通知 API エンドポイントへのアクセスを提供します。

2. 製品/チャネル:管理

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

さらに、チャネル、製品、およびさまざまなユースケースによって異なる他のスコープタイプがあります。使用可能なすべてのスコープは、[ APIキー の作成 (opens in a new tab) ] ページで確認できます。

API スコープの構成

API スコープを構成するには、使用する各 API エンドポイントへのアクセスを APIキー に許可する必要があります。これを行うには、まず API エンドポイントのドキュメントを確認します。必要なスコープが一覧表示されます。これらのいずれかを付与すると、APIキー がエンドポイントにアクセスできるようになります。

既存の APIキー を編集して新しいスコープを付与するか、最初からスコープを使用して新しいスコープを作成できます。

API キーは、 専用 API (opens in a new tab) または Web インターフェイスを使用して管理できます。

Web インターフェイスを使用してAPIスコープを構成する場合は、[開発者ツール] → [API キー] → [APIキーの作成 (opens in a new tab)] に移動します。

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

• 名前
• 作成日
• 有効期限
• 許可された IP アドレス (オプション)

次のセクション「APIスコープ」で、含めるスコープを選択します。

• 全般
• チャンネル
• 接続
• プラットホーム
• 顧客エンゲージメント
• Web SDK

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

使用可能な API スコープ

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

ユーザー ロールと API スコープ

APIキーを使用できず、基本認証に依存する必要がある場合は、呼び出しに使用しているパスワードのユーザーが API エンドポイントには、それらのエンドポイントにアクセスするために必要なスコープが付与されています。API キーとは異なり、スコープはユーザーに直接割り当てられません。 代わりに、ユーザーにロールを割り当てることができ、それらのロールは特定のスコープを暗黙的に付与します。

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

エラー

指定されたユーザーまたは APIキーに必要なスコープがない場合、応答で 403 Forbidden HTTP ステータス コードを受け取ります。

 
    {
        "requestError": {
            "serviceException": {
            "messageId": "FORBIDDEN",
            "text": "Forbidden"
            }
        }
    }
 

ライブラリの例外

ライブラリ (opens in a new tab)のいずれかを使用する場合は、必ずAPI例外を処理してください。

 
    try {
        SmsResponse smsResponse = sendSmsApi.sendSmsMessage(smsMessageRequest);
    } catch (ApiException apiException) {
        apiException.getCode();
        apiException.getResponseHeaders();
        apiException.getResponseBody();
    }
 

 
    try
    {
        var result = api.SendSmsMessage(smsRequest);
    }
    catch(ApiException apiException)
    {
        var errorCode = apiException.ErrorCode;
        var errorContent = apiException.ErrorContent;
    }