インテグレーションの認証

インテグレーションにおいて、API経由でPioにアクセスし、データを追加、更新、受信するには、認証トークンが必要です。次のセクションでは、登録したインテグレーションにおけるトークンの取得方法について説明します。このトークンは認証に使用され、Pio APIへのHTTPリクエストのヘッダーに含められます。

情報

現時点では、access_tokenに有効期限はありません。ただし、明示的に失効させた場合や、インテグレーションやショップが無効化された場合を除きます。

Pio APIには標準的な認証プロセスが採用され、OAuth 2.0に準拠しています。認証をスムーズに行うため、Pioシステムのユーザーに組織とショップが設定されていることを確認してください。Pio APIの認証手順は次のとおりです。

client_idとclient_secretを用意し、OAuthのフロー全体に対応したredirect_url/callback_urlを準備します。
インテグレーションを作成したら、Pio内の組織に対して認証を行う必要があります。管理者ユーザーとしてPioにログインし、ブラウザから次のURLにアクセスしてください。https://app.test.pio.com/raw/openapi_auth/authorize_form?client_id=<your-client-id>&redirect_uri=<your-redirect-url>

client_id（必須）をURLパラメーターとして指定します。その他にも必要なパラメーターがある場合、同じURLに追加できます。
redirect_uri（必須）は、認証リクエストの承認後にユーザーをインテグレーションへリダイレクトする際に使用します。
state（任意）を設定した場合、インテグレーションへのリダイレクト先のクエリ引数に含まれます。元のリクエストと最終的なコールバックを一致させる必要がある場合に使用してください。

上記のURLにclient_idを付けてアクセスすると、ログインしていない場合は次のようなログインウィンドウが表示されます。
管理者ユーザーでログインすると、次のような画面が表示されます。この認証フォームには、インテグレーションの名前とリクエストするすべてのscopeが表示されます。
Pioユーザーが[Authorize]を押すと、callback_urlにリダイレクトされます。このURLには、次の手順に必要なcodeが含まれています。

情報

codeはブラウザのURLで確認できます。

リダイレクトが実際にPioから行われたものかどうかを確認するには、hmacを使用してください。署名を確認するには、クエリ文字列からhmac=...&部分を削除し、残りの部分からHMAC-SHA256の署名を生成して、与えられたhmacと一致するか確認します。実際の例はこちらを参照してください。
上記の手順で取得したcodeを使用してAPIを呼び出すことで、access_tokenを取得できます。この際、code、client_id、client_secretを渡す必要があります。

処理の中で問題が発生した場合、最後に行った手順から再開できます。

複数のショップに対して認証を行う場合、以上の手順を繰り返してください。

注意

access_tokenは厳重に保管してください。トークンを紛失した場合、再度Pioユーザーによるログインが必要となります。