> ## Documentation Index
> Fetch the complete documentation index at: https://developers.authlete.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 2 段階の API 呼び出し
> INTERACTION などのアクションを /auth/authorization/issue または /auth/authorization/fail の 2 回目の API 呼び出しで完了させる方法と、2 つの呼び出しを連携するチケットの仕組みを説明します。
アクションの中には、1 回の API 呼び出しでは完了できないものがあります。[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API が `action=INTERACTION` を返した場合、認可サーバーはユーザーを認証して同意を取得しなければ認可リクエストに応答できません。そして、その応答は **2 回目**の Authlete API 呼び出しによって生成されます。
## 認可エンドポイント API の 2 つのタイプ
[認可エンドポイント API](/api-reference/authorization-endpoint) は 2 種類の API で構成されています。
1. 認可リクエストを解釈し、エンドユーザー認証など次のステップに必要な情報を提供する API
* [/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request)
2. トークンやコードを発行する、またはエラーを返す API
* [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response)、[/auth/authorization/fail](/api-reference/authorization-endpoint/fail-authorization-request)
`action=INTERACTION` の典型的なフローは次のとおりです。
```mermaid theme={null}
sequenceDiagram
autonumber
participant UA as Web ブラウザー
participant AS as 認可サーバー
participant API as Authlete Core API
UA ->> AS: 認可リクエスト
AS ->> API: POST /auth/authorization
API -->> AS: action=INTERACTION, ticket
AS ->> UA: 認証・同意画面
UA ->> AS: ユーザーが認証・同意
AS ->> API: POST /auth/authorization/issue (ticket)
API -->> AS: action=LOCATION, responseContent
AS ->> UA: 302 Found（認可コード）
```
## フローの各ステップ
### 認可リクエストと 1 回目の呼び出し
OAuth 2.0 / OpenID Connect のフローは、クライアントがエンドユーザーのブラウザーを認可サーバーの認可エンドポイントへリダイレクトすることで始まります。このとき送られるリクエスト（`response_type`、`client_id`、`redirect_uri`、`scope` などを含むクエリ文字列）が、上の図の「認可リクエスト」にあたります。
認可サーバーは、受け取ったリクエストを加工せずそのまま [/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) に渡します（詳細は[リクエストとレスポンス](/ja/get-started/concepts/request-and-response)を参照）。認可リクエストがエンドユーザーとの対話を必要とする場合、Authlete は次のようなレスポンスを返します。
```json theme={null}
{
"action": "INTERACTION",
"ticket": "cElOaH9j4mS6AiIGR9oLqHlDn9jpvcNjqSgyRqfcmAE",
"client": { "..." },
"service": { "..." }
}
```
* `action=INTERACTION` は「認可リクエストに応答する前にエンドユーザーとの対話（認証・同意）が必要」という意味です。
* `ticket` は、2 回目の呼び出しへ処理を引き継ぐための値です（性質は後述の「チケット」を参照）。
* レスポンスにはクライアント情報・サービス情報のほか、クライアントが要求したスコープやクレームも含まれます。認可サーバーはこれらを使って次の同意画面を組み立てます。
### 認証・同意画面の表示
**認証・同意画面の表示、ユーザー認証、同意の取得はいずれも認可サーバー自身の責務**であり、Authlete がこれらの画面を描画するわけではありません。認可サーバーは 1 回目のレスポンスに含まれる情報を使って同意画面を表示します。このあいだ、受け取った `ticket` は 2 回目の呼び出しまでサーバー側（セッションなど）で保持しておきます。
### 2 回目の呼び出しと認可レスポンスの生成
ユーザーが認証と同意を完了したら、認可サーバーは 2 回目の呼び出しとして [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) にリクエストを送ります。このリクエストには、1 回目で受け取った `ticket` と、認証したエンドユーザーの識別子である `subject` を含めます。
```bash theme={null}
curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization/issue \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "ticket": "{1 回目のレスポンスで受け取った ticket}", "subject": "{認証したエンドユーザーの識別子}" }'
```
別リージョンを利用している場合は `us.authlete.com` をご利用のクラスターホスト（`eu.authlete.com`、`jp.authlete.com` など）に置き換えてください。サービスアクセストークンの取得方法は[認証](/ja/get-started/concepts/authentication)を参照してください。
OpenID Connect の ID トークンを発行する場合は、`authTime`（ユーザーを認証した時刻）、`acr`（認証コンテキストクラス）、要求されたクレームの値などを併せて渡せます。渡せるパラメーターの一覧は [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) の API リファレンスを参照してください。
このリクエストが成功すると、レスポンスの `action` は通常 `LOCATION` になり、`responseContent` に認可コードを含むリダイレクト先 URL が入ります。認可サーバーはこの値を使ってブラウザーに `302 Found` を返し、認可レスポンスをクライアントに届けます。2 回目のレスポンスの `action` も[アクションハンドリング](/ja/get-started/concepts/action-handling)で説明したとおりに処理してください。
ユーザーがキャンセルした場合や認証に失敗した場合は、[/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) の代わりに [/auth/authorization/fail](/api-reference/authorization-endpoint/fail-authorization-request) を同じ `ticket` とともに呼び出します。Authlete がクライアント向けの適切なエラーレスポンスを構築します。
## チケット
前述のとおり、チケットは 1 回目の呼び出しの応答で発行され、2 回目の呼び出しで処理を完了させる一度限りの値です。次の性質があります。
* チケットは 24 時間で有効期限切れになります。期限切れのチケットは Authlete のデータベースから削除されます。
* チケットは一度しか使えません。チケットを含むリクエストを [/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) または [/auth/authorization/fail](/api-reference/authorization-endpoint/fail-authorization-request) が正常に処理した直後に削除されます。
* 使用済みまたは期限切れのチケットを使うと、次のようなエラーになります。
```
[A041202] There is no entity having the ticket specified
in the /api/auth/authorization/issue request (ticket = {Ticket}).
```
チケットは認可サーバーと Authlete サーバーの間でのみ使用するように設計されています。Web ブラウザーなどのユーザーエージェントに渡してはいけません。たとえば、チケットをセッション管理に使うことは避けてください。
## 2 段階の呼び出しが必要な API の例
他の 2 段階の呼び出しが必要な API の例としては userinfo エンドポイントがあげられます。
[/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request) API はクライアントが提示したアクセストークンを検証し、`action` を返します。アクションが `OK` の場合、サーバーはエンドユーザーのクレーム値を収集して [/auth/userinfo/issue](/api-reference/userinfo-endpoint/issue-userinfo-response) を呼び出し、userinfo レスポンスを構築します。クライアントの設定に応じて、Authlete がプレーンな JSON または署名・暗号化された JWT として整形します。userinfo エンドポイントはチケットを使いません。ここでは、2 つの呼び出し間の文脈をアクセストークン自体が引き継ぎます。
トークンエンドポイントにも 2 段階のバリエーションがあります。サービスがリソースオーナーパスワードクレデンシャルズグラントをサポートする場合、[/auth/token](/api-reference/token-endpoint/process-token-request) API は `action=PASSWORD` を返し、サーバーがエンドユーザーのクレデンシャルを検証したうえで [/auth/token/issue](/api-reference/token-endpoint/issue-token-response) または [/auth/token/fail](/api-reference/token-endpoint/fail-token-request) を呼び出します。`TOKEN_EXCHANGE`（[RFC 8693](https://www.rfc-editor.org/rfc/rfc8693)）や `JWT_BEARER`（[RFC 7523](https://www.rfc-editor.org/rfc/rfc7523)）でも同じパターンで、サーバーが subject token や assertion を検証します。
`action` ベースのモデルと 2 段階パターンを理解すれば、どの Core API も API リファレンスから自然に読み解けるようになります。