[API提供者向け] Postmanで自社提供APIのAPI Authガイド (Guided Auth) を設定する方法

この記事では、API提供者向けにAPI Authガイドの設定方法を解説します。

# API Authガイドとは？

API Authガイド ( Guided Auth ~~Easy Auth~~ とも言われている)とは、API提供者がパブリックに公開するAPIの認証認可の設定方法を利用者にわかりやすく伝えるためのヘルパー機能です。

API利用ユーザーがPostmanのAPIリクエスト設定において、あるエンドポイントのドメインを入力したとき、もしそのAPIに対して事前にAPI Authガイドが設定されていると、次のようなAPI Authガイドが表示されます。これにより、API利用者は迅速かつ効率的にAPIの認証・認可の設定に取り込むことができます。

![easy-auth-flow-v10-2.gif](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/24a88e4d-7928-27cd-d158-490bbbcdcfbb.gif)
(ref: [Set up Guided Auth for public APIs in Postman](https://learning.postman.com/docs/publishing-your-api/setting-up-authentication-for-public-apis/))

内部的には、エンドポイントのドメイン情報から自動的にPostmanが認識し、API提供者が事前に用意した手順を表示させ、利用者にAPIの認証・認可の設定を促します。

# API Authガイド設定手順

## 1. API認可ダッシュボードで公開APIのAPI Authガイド情報入力

API認可ダッシュボードにアクセスして、公開APIのAPI Authガイド情報を入力します。直接、[API認可ダッシュボードURL](https://web.postman.co/settings/team/api-authentication)にアクセスするか、または、`Team` > `Team Settings`を選択し、左サイドバーの`Set up API authorization`を選択します。

![Screenshot 2024-04-24 at 9.30.19.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/96b4bc77-d4b3-90d9-98c4-530c2c2202ce.png)

:::note 
補足: API Authガイドはチーム設定の１つ

API Authガイドの設定はチーム設定の１つです。もしチームに所属しない個人アカウントで[API認可ダッシュボード](https://web.postman.co/settings/team/api-authentication)にアクセスすると、次のようなチーム作成を促すモーダルが表示されます。

![Screenshot 2024-04-24 at 9.30.07.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/9ac640c9-78e4-3e34-4a74-f58ee3f9d11b.png)

チームを作成、もしくは既存のチームに所属してからAPI Authガイド設定をすすめてください。
:::

次に、API Authガイドの入力フォームに対象とするAPIの情報を入力します。入力項目には、下記イメージのように、API名、APIエンドポイントのベースURL、API認可タイプ、API認可タイプごとの属性情報、API Authガイド説明文などがあります。

![Screenshot 2024-04-24 at 9.30.44.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/ff8c3f80-b779-d4da-b02a-e765588d9e61.png)

また、APIドメインの検証が必要になります。入力されたAPIベースURLに含まれるドメイン名にもとづき下記のような内容のメッセージが表示されます。ここで`Generate TXT Record`をクリックしてAPIドメイン検証用のTXTレコードを作成してください。

![Screenshot 2024-04-24 at 16.34.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/15253a4c-3997-ac7d-1f6b-c8a6662bebbf.png)


## 2. APIドメインにTXTレコード追加

このステップでは、ステップ1で作成されたTXTレコードを、APIドメインのDNS設定に追加します。

次の例では、APIドメインのDNS設定に、タイプ`TXT`、名前`@`、値にステップ１で作成されたTXTレコード値、TTL`3600秒（1/2時間）`で設定してます。

![Screenshot 2024-04-24 at 9.31.24.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/a493c5b7-a48f-21be-ff75-ca98400dfc62.png)

TXTレコードを追加したら、次のように対象APIドメインのTXTレコードが参照できるか確認します。

```shell: digでTXTレコード参照 (APIドメイン: example-domain.com)
dig TXT example-domain.com
```
もし伝搬までに時間がかかる場合は、次のように直接DNSサーバを指定して確認するとよいでしょう。

```shell: 直接DNSサーバーを指定してdigでTXTレコード参照 (APIドメイン: example-domain.com)
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ドメインの検証をします。

![Screenshot 2024-04-24 at 16.02.48.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/eb1b7181-1a51-da3a-0d3c-87837a7e20c1.png)

無事ドメインが検証されたら、上記のようにDomain verifiedメッセージが表示されます。これでフォームを保存(Save)したら設定完了です。

# API Authガイドが表示されることを確認

全て設定が完了したら、最後にAPI Authガイドが表示されることを確認してください。PostmanのAPIリクエスト設定において、エンドポイント入力エリアに該当のドメインを入力すると、次のようなAPI認証認可ガイドが表示されるはずです。下記イメージは、APIキー認証のガイド表示の例です。

![Screenshot 2024-04-24 at 9.31.55.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/e46f7552-4234-e9bf-8d64-59f6e06bcb4b.png)

API Authガイドに従いAPIキーを取得して、フォームにAPIキーを入力すると、次のようにAPIキー認証に必要なフィールドが自動入力されます。

![Screenshot 2024-04-24 at 9.32.11.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/103420/3d1134c0-3d22-503f-417a-0a8f826c9326.png)

説明は以上です。

API利用者にとってAPI利用の障壁の１つは認証・認可設定です。是非、この機能を活用して利用者フレンドリーなガイドを提供していただけたらと思います。

API Authガイド設定の公式ページもあるのでこちらも参考にしてください。

https://learning.postman.com/docs/publishing-your-api/setting-up-authentication-for-public-apis/