KandaSearch REST API 認証

KandaSearch REST API を呼び出すために、クライアントアプリは各リクエストに対して認証トークンを指定する必要があります。この認証トークンは、Authorization ヘッダー内の値として設定します。

--header 'Authorization: Bearer ...'

... の部分はトークンの値に読み替えてください。

認証ヘッダーが提供されていない場合や、提供されたトークンがすでに期限切れの場合、リクエストは失敗します。トークンが期限切れとなった場合、クライアントアプリは KandaSearch REST API を引き続き使用するために新しいトークンを発行する必要があります。

クライアントアプリが認証トークンを取得するためには2つの方法があります。

  • 認証サービスに直接リクエストを送信する
  • KandaSearch の専用APIを呼び出す

いずれの方法も認証トークンを取得するためには正しい方法ですが、1つ目の方法には欠点があります。
まず第一に、認証サービスと直接やり取りすることはかなり複雑で、成功するために追加のデータを提供する必要があります。
第二に、認証サービスのURLが変更される可能性があります。
最後に、認証サービス自体が完全に異なるAPIを持つ別の認証サービスを使用するように切り替わる可能性があります。
それゆえ、長期的には1つ目の方法はあまり信頼性がありません。認証トークンを取得するためには、2つ目のKandaSearch APIを使用することを強くお勧めします。

KandaSearchは、認証トークンを取得するための専用のREST APIを提供しています。APIを使うことは、ユーザーの資格情報をトークンと交換することを意味します。
なお、このAPIはKandaSearchのユーザー資格情報取得時のみで動作します。つまり、外部の認証プロバイダー(GoogleGitLabなど)での認証はサポートされていません。
KandaSearch API を使って認証トークンを取得するには、次のURLに対してPOSTリクエストを実行する必要があります。

curl --location 'https://api.kandasearch.com/external/v1/auth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'username=...' \
--data-urlencode 'password=...'

上記のusernamepassword... の部分は実際のトークンの値で置き換える必要があります。
POSTのレスポンスでは、トークン値が含まれる文字列が返されます。このトークン値は、認証で保護されている他のKandaSearch REST APIを呼び出すためにも使用されています。

WindowsでcURLを使用する場合は、下記のように、すべての単一引用符'を二重引用符"に置き換え、かつ、コマンドを1行に収めるようにしてください。

curl --location "https://api.kandasearch.com/external/v1/auth/token" --header "Content-Type: application/x-www-form-urlencoded" --data-urlencode "username=..." --data-urlencode "password=..."