認証

Verify API は 2 種類の認証をサポートしています：

• 基本認証
• JWT

ベーシック認証とJWTのどちらを使うべきか？

Verify V2は2つの認証方法をサポートしている：Basic認証とJWTベアラ認証です。両者の違いを理解することは、スムーズな移行とV2の機能を最大限に活用するために重要です。

どちらのオプションも使えるが、両方を同時に使うことはできない。一般的には JWTを使用することをお勧めします。 認証を使用します。Basic認証の方が使い始めは簡単ですが、この認証では サイレント認証 チャンネル

基本認証

基本認証では、APIキーとAPIシークレットを送信します。 Base64エンコード での Authorization ヘッダで確認できます。これらの認証情報は API設定 をクリックします。

Verify V2 を使い始める最も簡単な方法です。Vonage Application のセットアップが不要で、認証情報は Vonageダッシュボード.

仕組み

Authorization: Basic <base64(api_key:api_secret)>

リクエストヘッダーの作成

• まず、API KeyとSecretを連結する： API_KEY:API_SECRET.
• それからだ、 Base64エンコード その結果もっと詳しく これ.
• 最後に、リクエストに Authorization: Basic BASE64_ENCODED_STRING.

これはアプリケーション・コードの中で、例えばJavaScriptの中で行うことができる：

const credentials = btoa('YOUR_API_KEY:YOUR_API_SECRET');

const response = await fetch('https://api-eu.vonage.com/v2/verify', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Basic ' + credentials
  },
  body: JSON.stringify({ ... })
});

リクエスト例

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Basic <base64(YOUR_API_KEY:YOUR_API_SECRET)>' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

からBase64エンコードされた文字列を生成できます。 api_key:api_secret 標準的なBase64エンコーディングツールやライブラリを使用する。

制限事項

Basic Authは、Verify V2のコアとなるリクエストフロー（送信、チェック、キャンセル、次のワークフローのトリガー）へのアクセスを提供するが、2つの重要な制限がある：

• コールバック/ウェブフックはサポートされていません。 イベントまたはサマリーコールバックを受信するには、ステータスURLで設定されたVonage Applicationとともに、JWTベアラ認証が必要です。
• ACL（アクセス制御リスト）のサポートはありません。 JWTトークンは、Basic Authでは不可能な、特定のAPIエンドポイントへのパーミッションのスコープを可能にします。

これらの制限を考慮すると、Basic認証は最初のテストやPOC統合に最適です。本番環境では、JWTベアラ認証を強く推奨します。

JWT

A JWT (JSON Web Token）は、オープンスタンダード(RFC 7519)を使用して、当事者間で情報をJSONオブジェクトとして安全に送信することができる。このオブジェクトはオプションで暗号化し、秘密鍵/公開鍵で署名することができます。

JWT ベアラ認証は、Vonage アプリケーションの秘密鍵で署名された JSON Web トークンを使用します。この方法は、イベントおよびサマリーコールバック、Webhook 設定、ACL スコープトークンを含む Verify V2 の全機能をアンロックします。

仕組み

Authorization: Bearer <JWT>

JWTはダッシュボードでVonageアプリケーションを作成する際に取得したアプリケーションIDと秘密鍵を使って生成されます。

JWTを生成するには application ID そして private keyこの2つは アプリケーション の設定を変更してください。 ダッシュボード.

新しいJWTを生成するにはいくつかの方法がある：

• を使用している。 JWTオンラインジェネレーター.

• を使用している。 Vonage CLIツール.秘密鍵とアプリケーションIDを提供しなければならない：

ご注意ください：

• Vonageのいずれかをご利用の場合 サーバーSDK すべてのSDKがJWTトークンの生成をサポートしているため、JWTを別途生成する必要はありません。

• Vonage SDKsのような外部ツールやライブラリを使用してJWTを生成したくない場合は、独自のJWT生成を実装することができます。その場合 JWTの生成方法 ブログ記事には、外部依存なしにJWTを生成する方法を示すJavaScriptとPythonの例が含まれています。

トークンが生成されると、ユーザーはそのトークンを使って保護されたエンドポイントにアクセスできるようになります。これは通常、Bearerスキーマを使用したAuthorizationヘッダーを使用して行われます：

Authorization: Bearer <JWT>

Verify V2のセットアップ手順

1. でVonageアプリケーションを作成します。 Vonageダッシュボード.
2. 公開鍵と秘密鍵のペアを生成し、秘密鍵をダウンロードして安全に保管する。
3. アプリケーションの Verify V2 を有効にし、コールバックを受信する Status URL（Webhook エンドポイント）を設定します。
4. アプリケーションIDと秘密鍵で署名されたJWTを生成します。その際 JWTジェネレーターその Vonage CLIまたは任意のVonage SDK。
5. を使用して、すべてのAPIリクエストにJWTを含めます。 Authorization: Bearer ヘッダーを使用する。

リクエスト例

curl --location --request POST 'https://api.nexmo.com/v2/verify' \
  --header 'Authorization: Bearer YOUR_JWT' \
  --header 'Content-Type: application/json' \
  --data-raw '{
    "brand": "Acme Inc.",
    "workflow": [
      { "channel": "sms", "to": "447700000000" }
    ]
  }'

JWTトークンは、最大TTL（time-to-live）が 24時間.を避けるために、有効期限が切れる前にトークンをリフレッシュするようにしてください。 401 Unauthorized というエラーが出た。

JWTが解き放つもの

• コールバックの概要 - すべての検証リクエストの最後に、完全なステータスレポートを受け取る。
• イベント・コールバック - 例えば、Silent AuthやWhatsApp Interactiveチャネルの場合）。
• ACLスコープ付きトークン - セキュリティを強化するために、トークンのパーミッションを特定のエンドポイントに制限する。
• ウェブフックの設定 - コンフィグ verify_event_url そして verify_status_url Vonageアプリケーションによる。

Verify Legacy (V1)からの認証の移行

Verify V1 から Verify V2 に移行する際の主な変更点の一つは、認証の処理方法である。

Verify V1 では、認証は次のように処理されました。 api_key そして api_secret をクエリ・パラメータまたはリクエスト・ボディとして使用する。このメソッドはVerify V2ではサポートされていません。