API 認証

統合で Infobip API を使用するには、認証方法を使用する必要があります。プライベートアプリの場合は、認証資格情報をアプリに埋め込むことができます。

複数のアカウントで使用されるアプリの場合、統合内の適切な機能に各ユーザーを接続するために、ユーザーのInfobipアカウント情報をキャプチャする必要がある場合があります。

これの一般的な使用例は、Infobip アカウントを外部プラットフォームのアカウントに接続することです。OAuth 2.0を使用して、トークンでアカウント、ユーザー、および追加情報を取得できます。

認証方法を選択する

次の表に、選択する認証方法を選択する際に役立つ情報を示します。

認証方法	APIキー	OAuthの2.0
セキュリティレベル	モデレート – 簡単に傍受または共有できます	高 – トークンは存続期間が短く、スコープが限定されています
実装作業	実装と使用が簡単	トークン管理とフローの設定が必要
API 統合に適しています	✔	✔
アカウントとユーザーの情報を取得する	✖
Infobip API を使用する	✔	✔
埋め込み UI(設定ページ、コンテキストカード)に使用	✖	✔
ベスト・フォー	1つのアカウントで使用する限定公開アプリ	複数のアカウントで使用するアプリ
最適な結果を得るにはスコープを使用する	✔	✔

API キー

API キーを使用する場合は、適切な API スコープがAPIキーに割り当てられていることを確認します。API キーは Infobip アカウントに関連付けられているため、キーが暗号化され、セキュリティで保護されていることを確認するための手順を実行します。

OAuth 2.0 (英語)

OAuth 2.0 は、ログイン資格情報の代わりに識別トークンを渡すことで、別のサイトからのデータを共有できるようにする承認プロトコルです。

OAuth を使用すると、Exchange アプリは、パスワードを取得せずに、ユーザーの Infobip Web インターフェイスアカウントの詳細に対する承認を要求し、承認された API 機能にアクセスできます。

つまり、アプリケーションは、アプリが Infobip Web インターフェイスユーザーの代わりに動作できるようにするトークンを要求します。全体的な承認フローは次のようになります。

アプリのユーザーエクスペリエンス

アプリをインストールするユーザー、またはOAuth経由で認証するユーザーは、次の手順を使用します。

サイトまたはアクティブ化ページから、ユーザーは Infobip にリダイレクトするリンクをアクティブ化します。
必要に応じて、ユーザーは自分の Infobip アカウントにログインします。
ユーザーは、OAuth 接続に必要なアクセス許可 (スコープ) を確認します。
ユーザーは、必要なアクセス許可を受け入れるか、インストールをキャンセルします。
ユーザーがインストールを取り消すと、参照元の Web ページに再ルーティングされます。
ユーザーがアクセス許可を受け入れた場合、認証は完了し、ユーザーはリダイレクト URL にリダイレクトされます。

OAuth 2.0 を使用して、統合またはプラットフォームでユーザーを認証する

アプリでOAuthを使用するには:

アプリシェルを作成して、アプリの一意のクライアント ID とクライアントシークレット (OAuth フローのユーザー名とパスワードなど) を作成し、アプリに必要なスコープを割り当てます。
1. OAuth フロー中に使用するアプリのリダイレクト URI を入力します。
2. アプリの [クライアント ID] と [クライアントシークレット] を取得します。これらの値はアプリに固有であり、Infobip との通信に役立ちます。コピーアイコンを使用して、シークレットをクリップボードにコピーします。
サイトアクティベーションリンクを作成します。Web ページまたはプラットフォームで、ユーザーが Infobip に接続できるリンクを作成します。

リダイレクト URI を設定する

認証されたユーザーがアプリを承認し、クライアント ID とシークレットが有効な場合、Infobip は、クエリパラメーターとしての一時コードと、手順 1 で指定した状態パラメーターを使用して、redirect_uriへの要求を作成します。

[redirect_uri?code={code}&state={state}]

状態を照合して、この OAuth フローに対して要求が生成されたことを検証できます。

code - [必須] - 16 文字の 16 進文字列の権限付与コード。
state - [オプション] - 前の要求と同じです。

たとえば、[https://www.my-app.com/?code=822762fa24e04975&state=xyz] のようになります。

これは権限付与コードです。権限付与コードは一度だけ交換でき、作成後 1 分で有効期限が切れます。

トークンのコードをExchangeする

次の段階では、コードをトークンと交換する必要があります。

手順 2 (サイトアクティベーションリンクの作成) を正常に完了したら、POST メソッドを使用して Get Token エンドポイント [https://oneapi.infobip.com/exchange/1/oauth/token] を呼び出して、アクセストークンのコードを交換します。
URL エンコード本文要求 (--data-urlencode) として次の値を渡します。
- client_id - [必須] - 32 文字の 16 進数文字列のパブリックアプリ識別子
- client_secret - [必須] - AES 暗号化アルゴリズムを使用する 256 ビットキーの 16 進数表現であるプライベートアプリ識別子
- code - [必須] - 手順 2 で承認サーバーから受信した一時的な承認コード
- redirect_uri - [必須] - 手順 1 以降の承認要求と同じredirect_uri
- grant_type - [必須] - 標準でauthorization_codeに設定する必要があります

例えば：


    curl --location --request POST 'https://oneapi.infobip.com/exchange/1/oauth/token' \    --header 'Accept: application/json' \    --header 'Content-Type: application/x-www-form-urlencoded' \    --data-urlencode 'client_id=d5e47f02d627e390d615c2e93f168eb6' \    --data-urlencode 'client_secret=YED8Q0KHeYgQxtjdUkR376Uxu0/zdvwAVZb3ZQ3GGZU=' \    --data-urlencode 'code=822762fa24e04975' \    --data-urlencode 'redirect_uri=https://www.my-app.com' \    --data-urlencode 'grant_type=authorization_code'

トークンとその他のユーザー情報を含む JSON 応答を受け取ります。

token - [必須] - Infobip トークン
tokenType - [必須] - IBSSO
accountKey - [必須] - 要求からの accountId を表す 16 進数の文字列
userKey - [必須] - 要求からの userId を表す 16 進数の文字列
username - [必須] - Infobip Web インターフェイスのユーザー名が登録されています
email - [必須] - Infobip Web インターフェイスの電子メールが登録されました
ロケール - [必須] - ユーザーによって定義された Infobip Web インターフェイス言語
roles - [オプション] - Infobip Web インターフェイスユーザーロールのリスト
グループ - [オプション] - Infobip Web インターフェイスユーザーグループの一覧

以下は JSON の例です。

 
{    "token": "3d7908aa-7b8c-4c5a-94bf-5cdeef18947b",    "tokenType": "IBSSO",    "accountKey": "8F0792F86035A9F4290821F1EE6BC06A",    "userKey": "F443BCAEB8517F7159F44D0E8CFE725D",    "username": "developeruser",    "email": "developer@infobip.com",    "locale": "en-US",    "roles": [    {    "id": 79,    "name": " Manager 1"    },    {    "id": 81,    "name": " Manager 2"    },    {    "id": 1297,    "name": " Manager 3"    },    {    "id": 1393,    "name": " Designer"    },    {    "id": 1394,    "name": " Supervisor"    }    ],    "groups": [    {    "id": 54004,    "name": "Group1"    },    {    "id": 54242,    "name": "Group2"    },    {    "id": 749187,    "name": "Group3"    }    ]    }

これがOAuthトークンです。トークンの有効期限は作成後 1 分です。

OAuthトークンの使用

トークンを取得したので、Infobip エンドポイントを呼び出すときの認証方法として使用できます。

承認するには、ヘッダーにトークンを追加する必要があります。

権限付与 - [必須] - {tokenType + " " + token}

次に例を示します (SMS メッセージを送信する場合)。


curl -L -X POST 'https://3vzg6v.api.infobip.com/sms/2/text/advanced' \    -H 'Authorization: IBSSO 3d7908aa-7b8c-4c5a-94bf-5cdeef18947b' \    -H 'Content-Type: application/json' \    -H 'Accept: application/json' \    --data-raw '{      "messages": [        {          "destinations": [            {              "to": "41793026727"            }          ],          "from": "InfoSMS",          "text": "This is a sample message"        }      ]    }'

更新トークン

アカウントの Infobip サービスに引き続きアクセスするには、有効期限が切れる前にトークンを更新します。これを行うには、Get Token エンドポイントをもう一度呼び出します。

[ https://oneapi.infobip.com/exchange/1/oauth/token ]

code - [必須] – 手順 4 で取得した権限付与トークン。
grant_type - [必須] – トークンの拡張refresh_token

要求が有効な場合、応答は上記の例と同じになります。

必要に応じて、トークンの更新を続行します。

Infobip Web インターフェイスに埋め込まれた UI に OAuth 2.0 を使用する

Conversations コンテキストカードまたはアプリ設定ページの Infobip Web インターフェイスに独自の UI を埋め込むことができます。OAuth を使用して顧客アカウント情報を取得し、UI の機能を強化することができます。埋め込みUIでOAuthを使用するには:

アプリシェルを作成するを使用して、アプリの一意のクライアント ID とクライアントシークレット (OAuth フローのユーザー名とパスワードなど) を作成します。
OAuth フロー中に使用されるアプリのリダイレクト URI を設定します。
アプリの [クライアント ID] と [クライアントシークレット] を取得します。これらの値はアプリに固有であり、Infobip との通信に役立ちます。コピーアイコンを使用して、シークレットをクリップボードにコピーします。

OAuthによる顧客アカウント情報の取得

アプリのオンボードフローにステップを作成して、Infobip でアプリを承認します。通常、これはアプリの構成ページやコンテクストカードページでトリガーできます。

クライアントのアクセスコードを取得するには、次の手順を実行します。

Infobip は、ページを iframe に読み込むときに、ユーザーの状態パラメーターを URL に渡します。例えば：

https://yoursite.com/contextcardui?state= WeHH_yy2irpl8UY

アプリでは、この状態値を一時的に保存し、この Authorize エンドポイントを使用して GET メソッドで承認のために送信する必要があります。

https://oneapi.infobip.com/exchange/1/oauth/authorize

クエリパラメーターとして次の値を渡す必要があります。
- response_type - [必須] - 応答として承認コードが必要であることを示すコード
- client_id - [必須] - 32 文字の 16 進数文字列のパブリックアプリ識別子
- state - [必須] - アプリへのリダイレクト要求に含まれる値
- redirect_uri - [必須] リクエストをアプリにリダイレクトするURL
- scope - [必須] - 追加のアクセスレベル
例：
http
```
    https://oneapi.infobip.com/exchange/1/oauth/authorize?response_type=code&client_id=d5e47f02d627e390d615c2e93f168eb6&state=xyz&redirect_uri=https://www.my-app.com&scope=api_read
 
```
認証されたユーザーによってページが読み込まれ、クライアント ID とシークレットが有効な場合、Exchange は、クエリパラメーターとして一時コードと、手順 1 で指定した state パラメーターを使用して、'redirect_uri への要求を作成します。

redirect_uri?code={code}&state={state}

この OAuth フローに対して要求が生成されたことを検証するために、状態を照合できます。
- code - [必須] - 16 文字の 16 進文字列の権限付与コード。
- state - [オプション] - 前の要求と同じです。
例：
http
```
    https://www.my-app.com/?code=822762fa24e04975&state=xyz
 
```
これは権限付与コードです。権限付与コードは一度だけ交換でき、作成後 1 分で有効期限が切れます。
手順 2 が正常に完了したら、次の Get Token エンドポイントを POST メソッドで呼び出して、アクセストークンのコードを交換します。

https://oneapi.infobip.com/exchange/1/oauth/token

URL エンコード本文要求として次の値を渡す必要があります (--data-urlencode)。
- client_id - [必須] - 32 文字の 16 進数文字列のパブリックアプリ識別子
- client_secret - [必須] - AES 暗号化アルゴリズムを使用する 256 ビットキーの 16 進数表現であるプライベートアプリ識別子
- code - [必須] - 手順 2 で承認サーバーから受信した一時的な承認コード
- redirect_uri - [必須] - 手順 1 以降の承認要求の同一の redirect_uri
- grant_type - [必須] - 標準では authorization_code に設定する必要があります
例えば：
curl
```
    curl --location --request POST 'https://oneapi.infobip.com/exchange/1/oauth/token' \
    --header 'Accept: application/json' \
    --header 'Content-Type: application/x-www-form-urlencoded' \
    --data-urlencode 'client_id=d5e47f02d627e390d615c2e93f168eb6' \
    --data-urlencode 'client_secret=YED8Q0KHeYgQxtjdUkR376Uxu0/zdvwAVZb3ZQ3GGZU=' \
    --data-urlencode 'code=822762fa24e04975' \
    --data-urlencode 'redirect_uri=https://www.my-app.com' \
    --data-urlencode 'grant_type=authorization_code'
```
トークンとその他のユーザー情報を含む JSON 応答を受け取ります。
- token - [必須] - Infobip トークン
- tokenType - [必須] - IBSSO
- accountKey - [必須] - 要求からの accountId を表す 16 進数の文字列
- userKey - [必須] - 要求からの userId を表す 16 進数の文字列
- username - [必須] - Infobip Web インターフェイスのユーザー名が登録されています
- email - [必須] - Infobip Web インターフェイスの電子メールが登録されました
- ロケール - [必須] - ユーザーによって定義された Infobip Web インターフェイス言語
- roles - [オプション] - Infobip Web インターフェイスユーザーロールのリスト
- グループ - [オプション] - Infobip Web インターフェイスユーザーグループの一覧
以下は JSON の例です。
json
```
{
    "token": "3d7908aa-7b8c-4c5a-94bf-5cdeef18947b",
    "tokenType": "IBSSO",
    "accountKey": "8F0792F86035A9F4290821F1EE6BC06A",
    "userKey": "F443BCAEB8517F7159F44D0E8CFE725D",
    "username": "developeruser",
    "email": "developer@infobip.com",
    "locale": "en-US",
    "roles": [
    {
    "id": 79,
    "name": " Manager 1"
    },
    {
    "id": 81,
    "name": " Manager 2"
    },
    {
    "id": 1297,
    "name": " Manager 3"
    },
    {
    "id": 1393,
    "name": " Designer"
    },
    {
    "id": 1394,
    "name": " Supervisor"
    }
    ],
    "groups": [
    {
    "id": 54004,
    "name": "Group1"
    },
    {
    "id": 54242,
    "name": "Group2"
    },
    {
    "id": 749187,
    "name": "Group3"
    }
    ]
    }
```

トークンを取得したので、Infobip エンドポイントを呼び出すときに認証方法として使用できます。

承認を受けるには、ヘッダーにトークンを追加する必要があります。

Authorization - [Required] - {tokenType + " " + token}

例 ( SMS メッセージを送信する (opens in a new tab)場合):

curl


    curl -L -X POST 'https://3vzg6v.api.infobip.com/sms/2/text/advanced' \
    -H 'Authorization: IBSSO 3d7908aa-7b8c-4c5a-94bf-5cdeef18947b' \
    -H 'Content-Type: application/json' \
    -H 'Accept: application/json' \
    --data-raw '{
      "messages": [
        {
          "destinations": [
            {
              "to": "41793026727"
            }
          ],
          "from": "InfoSMS",
          "text": "This is a sample message"
        }
      ]
    }'

シングルページアプリケーションのために顧客に代わって顧客のアカウントにアクセスする

ネイティブアプリやシングルページアプリなど、クライアントシークレットを格納できないアプリケーションの場合は、コード Exchange の証明キー (PKCE) フローを使用します。