この記事では、API提供者向けにAPI Authガイドの設定方法を解説します。
API Authガイドとは？
API Authガイド ( Guided Auth Easy Auth とも言われている)とは、API提供者がパブリックに公開するAPIの認証認可の設定方法を利用者にわかりやすく伝えるためのヘルパー機能です。
API利用ユーザーがPostmanのAPIリクエスト設定において、あるエンドポイントのドメインを入力したとき、もしそのAPIに対して事前にAPI Authガイドが設定されていると、次のようなAPI Authガイドが表示されます。これにより、API利用者は迅速かつ効率的にAPIの認証・認可の設定に取り込むことができます。
(ref: Set up Guided Auth for public APIs in Postman)
内部的には、エンドポイントのドメイン情報から自動的にPostmanが認識し、API提供者が事前に用意した手順を表示させ、利用者にAPIの認証・認可の設定を促します。
API Authガイド設定手順
1. API認可ダッシュボードで公開APIのAPI Authガイド情報入力
API認可ダッシュボードにアクセスして、公開APIのAPI Authガイド情報を入力します。直接、API認可ダッシュボードURLにアクセスするか、または、Team > Team Settingsを選択し、左サイドバーのSet up API authorizationを選択します。
補足: API Authガイドはチーム設定の１つ
API Authガイドの設定はチーム設定の１つです。もしチームに所属しない個人アカウントでAPI認可ダッシュボードにアクセスすると、次のようなチーム作成を促すモーダルが表示されます。
チームを作成、もしくは既存のチームに所属してからAPI Authガイド設定をすすめてください。
次に、API Authガイドの入力フォームに対象とするAPIの情報を入力します。入力項目には、下記イメージのように、API名、APIエンドポイントのベースURL、API認可タイプ、API認可タイプごとの属性情報、API Authガイド説明文などがあります。
また、APIドメインの検証が必要になります。入力されたAPIベースURLに含まれるドメイン名にもとづき下記のような内容のメッセージが表示されます。ここでGenerate TXT RecordをクリックしてAPIドメイン検証用のTXTレコードを作成してください。
2. APIドメインにTXTレコード追加
このステップでは、ステップ1で作成されたTXTレコードを、APIドメインのDNS設定に追加します。
次の例では、APIドメインのDNS設定に、タイプTXT、名前@、値にステップ１で作成されたTXTレコード値、TTL3600秒（1/2時間）で設定してます。
TXTレコードを追加したら、次のように対象APIドメインのTXTレコードが参照できるか確認します。
dig TXT example-domain.com
もし伝搬までに時間がかかる場合は、次のように直接DNSサーバを指定して確認するとよいでしょう。
dig TXT example-domain.com @example.dnsserver.com
次のようにANSWER SECTIONに追加したTXTレコードが表示されたら成功です。
;; ANSWER SECTION:
example-domain.com. 3600 IN TXT "postman-domain-verification=81e7aae8d6e7656074b9b7b0aa78d967bb9fb1b77837c606a029c317de6a2cab0faa39d4dcd1ea4235b2fa5409a*************************************"
3. APIドメインの検証とAPI Authガイド設定を完了させる
TXTレコードの追加が完了したら、再びフォームに戻り、次のようにVerfify DomainボタンをおしてAPIドメインの検証をします。
無事ドメインが検証されたら、上記のようにDomain verifiedメッセージが表示されます。これでフォームを保存(Save)したら設定完了です。
API Authガイドが表示されることを確認
全て設定が完了したら、最後にAPI Authガイドが表示されることを確認してください。PostmanのAPIリクエスト設定において、エンドポイント入力エリアに該当のドメインを入力すると、次のようなAPI認証認可ガイドが表示されるはずです。下記イメージは、APIキー認証のガイド表示の例です。
API Authガイドに従いAPIキーを取得して、フォームにAPIキーを入力すると、次のようにAPIキー認証に必要なフィールドが自動入力されます。
説明は以上です。
API利用者にとってAPI利用の障壁の１つは認証・認可設定です。是非、この機能を活用して利用者フレンドリーなガイドを提供していただけたらと思います。
API Authガイド設定の公式ページもあるのでこちらも参考にしてください。