> ## 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.

# アクションハンドリング

> Core API レスポンスの action フィールドによる分岐処理と、各アクションを認可サーバーが返す HTTP レスポンスへ対応づける方法を説明します。

ほとんどの Core API のレスポンスには `action` フィールドが含まれます。Authlete を用いた認可サーバー実装の原則はシンプルです。Core API を呼び出し、レスポンスをパースし、`action` の値を確認して、その値に応じた処理を行います。

<Warning>
  `resultCode` の値を処理の分岐条件に使っては**いけません**。
</Warning>

アクションのセットは Core API ごとに定義されていますが、その値は 2 つのパターンに分かれます。クライアントへの HTTP レスポンスに直接対応するアクションと、2 つ目の Authlete API 呼び出しが必要なアクションです。

```mermaid theme={null}
flowchart TD
    Start(["Core API のレスポンス"]) --> D{"action"}

    D -->|"直接レスポンス（例：LOCATION）"| L["responseContent から<br/>HTTP レスポンスを構築"]

    D -->|"2 段階呼び出し（例：INTERACTION）"| Work["サーバー側の処理<br/>（例：ユーザー認証）"]
    Work --> Next["次の Authlete API を呼び出す"]
    Next -.->|"レスポンスにも action が含まれる"| D
```

このページでは [/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API のアクションを例にモデルの動作を説明し、続いて他の Core API で登場する**代表的な**アクションを紹介します。このページに挙げるのは代表例であり網羅的なリストではないため、呼び出す API の API リファレンスを必ず確認してください。

## /auth/authorization のアクション

[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API のレスポンスの `action` フィールドには、次のいずれかの値が含まれます。

| アクション                   | 意味                                          | サーバーが行うこと（例）                                                                                |
| ----------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `INTERACTION`           | 認可リクエストは有効で、ユーザーとの対話が必要です。                  | 2 回目の API 呼び出しに進みます。[2 段階の API 呼び出し](/ja/get-started/concepts/two-step-api-calls)を参照してください。 |
| `NO_INTERACTION`        | リクエストは有効で、ユーザーとの対話は不要です（`prompt=none` など）。  | 2 回目の API 呼び出しに進みます。[2 段階の API 呼び出し](/ja/get-started/concepts/two-step-api-calls)を参照してください。 |
| `LOCATION`              | リダイレクトレスポンスを返すべき状態です。                       | `responseContent` を `Location` ヘッダーとして `302 Found` を返します。                                   |
| `FORM`                  | フォーム POST レスポンスを返すべき状態です。                   | `responseContent`（HTML フォーム）をボディとして `200 OK` を返します。                                         |
| `BAD_REQUEST`           | 認可リクエストが不正です。                               | `responseContent` をボディとして `400 Bad Request` を返します。                                          |
| `INTERNAL_SERVER_ERROR` | Authlete 側でエラーが発生したか、Authlete へのリクエストが不正です。 | `responseContent` をボディとして `500 Internal Server Error` を返します。                                |

レスポンスには `action` のほかに、クライアントの表示情報や要求されたスコープ・クレームなど、認可サーバーが認証・同意画面を組み立てるために必要な情報も含まれます。レスポンスの完全なスキーマは [API リファレンス](/api-reference/authorization-endpoint/process-authorization-request)を参照してください。

## アクションと HTTP レスポンスの対応

多くのアクションは、クライアントへ返す 1 つの HTTP レスポンスに直接対応します。認可サーバーは `responseContent` をそのレスポンスの本体やヘッダーに使います。
たとえば、Authlete Core API からの応答の `action` が `BAD_REQUEST` の場合、認可サーバーは次のようなレスポンスをクライアントに返します。

```
HTTP/1.1 400 Bad Request
Content-Type: application/json
Cache-Control: no-store
Pragma: no-cache

(responseContent)
```

`action` が `LOCATION` の場合は次のとおりです。

```
HTTP/1.1 302 Found
Location: (responseContent)
Cache-Control: no-store
Pragma: no-cache
```

## 追加のステップが必要なアクション

`INTERACTION` と `NO_INTERACTION`、そして `PASSWORD`・`TOKEN_EXCHANGE`・`JWT_BEARER` のようなグラント処理系のアクションは、1 つの HTTP レスポンスを返すだけでは処理を完了できません。ユーザーの認証や同意の取得などサーバー自身の処理を行ったうえで、2 つ目の Authlete API を呼び出して処理を完了する必要があります。このパターンは[2 段階の API 呼び出し](/ja/get-started/concepts/two-step-api-calls)で説明します。

## 他の API の代表的なアクション

他の Core API も、それぞれ固有のアクションセットで同じ規約に従います。次に挙げるのは代表的なアクションであり、網羅的なリストではありません。

| アクション                                    | API の例                                                                                                                                                                      | サーバーが行うこと（例）                                                                                                                                                                               |
| ---------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OK`                                     | [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request)、[/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request) ほか多数 | リクエストの処理に成功しました。通常は `responseContent` を `200 OK` で返すか、次の処理に進みます（`/auth/userinfo` の場合はクレーム値を収集して [/auth/userinfo/issue](/api-reference/userinfo-endpoint/issue-userinfo-response) を呼び出します）。 |
| `CREATED`                                | [/client/registration](/api-reference/client-management/create-client)                                                                                                      | リソースが作成されました（ダイナミッククライアント登録など）。`responseContent` を `201 Created` で返します。                                                                                                                    |
| `UNAUTHORIZED`                           | [/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request)、[/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request)      | 提示されたトークンが不正です。`responseContent` を `WWW-Authenticate` ヘッダーとして `401 Unauthorized` を返します。                                                                                                    |
| `INVALID_CLIENT`                         | [/auth/token](/api-reference/token-endpoint/process-token-request)、[/auth/revocation](/api-reference/revocation-endpoint/process-revocation-request)                        | クライアント認証に失敗しました。API リファレンスの記載に従い `400` または `401` を返します。                                                                                                                                    |
| `FORBIDDEN`                              | [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request)、[/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request)      | アクセストークンは有効ですが、要求されたリソースに必要なスコープ（やリソース）を持っていません。`403 Forbidden` を返します。                                                                                                                     |
| `NOT_FOUND`                              | [/gm](/api-reference/grant-management-endpoint/process-grant-management-request)                                                                                            | 対象リソースが存在しません（例：Grant Management リクエストで指定された `grant_id` が存在しない場合）。`404 Not Found` を返します。                                                                                                   |
| `PASSWORD`、`TOKEN_EXCHANGE`、`JWT_BEARER` | [/auth/token](/api-reference/token-endpoint/process-token-request)                                                                                                          | トークン発行の判断の前に、サーバー自身による検証（ユーザークレデンシャル、subject token、assertion）が必要です。[2 段階の API 呼び出し](/ja/get-started/concepts/two-step-api-calls)を参照してください。                                                 |

<Note>
  新しい世代の API（`/vci/*`、`/gm` など）では、エラーの発生箇所を区別します。`CALLER_ERROR` は実装側のリクエスト誤りを、`AUTHLETE_ERROR` は Authlete 内部のエラーを意味します。
</Note>