Postman 簡単認証 (Guided Auth) を使ってNotion APIをコールする

この記事はPostman Adventcalender 2024 12月24日の記事です。

過去こちらの記事などでPostmanのブルーバッジワークスペースを紹介しました。
https://qiita.com/KameMan/items/c6363c539209d9d1b123
ブルーバッジワークスペースはPostmanにより認定されたワークスペースで自分のワークスペースにフォークしてコピーすることで、あらかじめ必要なAPIコールが一式設定された環境を使うことができ、すぐテストに入れる便利な環境です。

Notion等一部のブルーバッジワークスペースにはGuided AuthというPostmanからの検証専用認証方式に対応しており、これを利用することで時間のかかる初期設定である認証設定を簡素化させることが出来ます。

Postman 簡単認証（Guided Auth） とは

https://learning.postman.com/docs/publishing-your-api/setting-up-authentication-for-public-apis/
Postmanが提供するAPIの認証プロセスを簡単に設定するためのガイド機能です。これを使用すると、APIリクエストを送信する際に、認証が必要な場合に、Postmanがその設定を支援してくれます。

ブルーバッジワークスペースにあらかじめ設定されているだけではなく、自分でワークスペース専用に認証をあらかじめ設定しておくことが可能です。
こちら にアクセスを行います。

Add Guided Authをクリックします。
設定手順は以下の通りです。

1. ベースURLの認証
   
   あらかじめPostmanに認証を行うURLが承認されている必要があります。
   これは呼び出されるAPIのドメインに対して行われるべきものです。つまりGuided Authを用いるためにはAPI側があらかじめそれに対応している必要があります。
   https://learning.postman.com/docs/publishing-your-api/setting-up-authentication-for-public-apis/#verify-your-domain
   2.認証タイプの選択
   
   OAuth 2.0, Bearer Token, Basic Auth, API Keyの４つに対応しています。PostmanではOAuth 2.0を推奨しています。
   3.認証方式の選択
   
   4.各種パラメータのセット
   
   ここがGuided Authのポイントです。
   通常のOAuth2.0ではリダイレクトURIを通じで認証コードの取得が最初のステップで行われます。その後その認証コードを使ってアクセストークンを取得します。そしてそのアクセストークンを使ってAPI呼び出しを行います。

例えば以下のようになります。

認証コード取得

GET https://example.com/oauth/authorize?
    response_type=code&
    client_id=your-client-id&
    redirect_uri=https://yourapp.com/callback&
    scope=read%20write

この処理においてhttps://yourapp.com/callback?code=authorization_code
へリダイレクトされ認証コードを取得します。次に取得した認証コードを用いてアクセストークンを取得します。

アクセストークン取得

curl -X POST https://example.com/oauth/token \
  -d "grant_type=authorization_code" \
  -d "code=authorization_code" \
  -d "redirect_uri=https://yourapp.com/callback" \
  -d "client_id=your-client-id" \
  -d "client_secret=your-client-secret"

そしてAPIコールを行います。

つまりとても煩雑です。Guided AuthではPostmanが生成したCall Back URLを用いることでそれらの設定が自動化され、APIコールがワンステップで行えるようになります。

さっそくやってみる

今日はNotionのAPIを試してみます。アカウントが無い方は無償プランでアカウントを作成しておきます。
以下の通りNotionのブルーバッジワークスペースを自分のワークスペースにフォークしておきます。

Retrieve a Userの認証タブでGuided AuthのOAuth 2.0を選択します。

Authorizeボタンを押します。

ブラウザ別タブでPostmanに権限を付与していいかを尋ねるNotionの画面が出ますのでアクセスを許可します。

上手くいけばこのようにTokenがセットされます。

あとは送信ボタンを押せば200が元って以下のレスポンスが得られるはずです。

{
    "object": "list",
    "results": [
        {
            "object": "user",
            "id": "151d872b-594c-818b-b084-0002c5dce2b8",
            "name": "kameman",
            "avatar_url": null,
            "type": "person",
            "person": {}
        },
        {
            "object": "user",
            "id": "160d872b-594c-81a7-9d6f-00275a776219",
            "name": "Postman",
            "avatar_url": "https://s3-us-west-2.amazonaws.com/public.notion-static.com/1a3fc387-dfee-49cf-8fe3-d2702879fea8/download.png",
            "type": "bot",
            "bot": {
                "owner": {
                    "type": "user",
                    "user": {
                        "object": "user",
                        "id": "151d872b-594c-818b-b084-0002c5dce2b8",
                        "name": "kameman",
                        "avatar_url": null,
                        "type": "person",
                        "person": {}
                    }
                },
                "workspace_name": "kamemanさんのNotion"
            }
        }
    ],
    "next_cursor": null,
    "has_more": false,
    "type": "user",
    "user": {},
    "developer_survey": "https://notionup.typeform.com/to/bllBsoI4?utm_source=postman",
    "request_id": "5e442fc2-5cfa-48af-afd9-aa89976073e0"
}

Guided Authを使わない場合、以下のOAuth 2.0認証に必要なものを全て入力しないといけないので、かなり簡単になっていることがわかります。

Postman Vault との連携

過去Postman Vault というローカル開発環境に安全にクレデンシャルを保存できるサービスについて紹介しました。
https://qiita.com/KameMan/items/e91ceafd52cb208fe1b0
Guided Auth用トークンも数クリックでそこに保存させることが可能です。




Vaultを使わない場合トークンはPostmanクラウド側に保存されています。Postmanクラウドも安全ですが、責任分界点の明確化のためにトークンはVaultを用いてローカルに保存することをお勧めします。