> ## 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.
# リクエストとレスポンス
> Authlete Core API に共通するリクエスト・レスポンスの構造、リクエストパラメーター処理の原則と、resultCode・action・responseContent の読み方を説明します。
**Core API** は、[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request)、[/auth/token](/api-reference/token-endpoint/process-token-request)、[/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request) など、OAuth 2.0 / OpenID Connect のプロトコルリクエストを処理する Authlete API 群です。認可サーバーはクライアントアプリケーションからのリクエストを自身のエンドポイントで受け取り、プロトコル処理を Core API に委譲します。
このページでは、Core API に共通するリクエスト・レスポンスの構造を説明します。
```mermaid theme={null}
sequenceDiagram
autonumber
participant C as クライアントアプリケーション
participant AS as 認可サーバー
participant API as Authlete Core API
C ->> AS: プロトコルリクエスト（認可リクエストなど）
Note over AS: パラメーターをそのまま渡す
AS ->> API: POST /auth/...（JSON ボディ）
API -->> AS: resultCode, action, responseContent, ...
Note over AS: action で分岐
AS -->> C: responseContent から HTTP レスポンスを構築
```
## リクエスト形式
Core API は JSON ボディを持つ HTTP POST リクエストを受け付けます。`Authorization` ヘッダーにはサービスアクセストークンを指定します。
```bash theme={null}
curl -s -X POST https://us.authlete.com/api/{Service ID}/auth/authorization \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "parameters": "response_type=code&client_id=YOUR_CLIENT_ID&redirect_uri=https%3A%2F%2Fclient.example.org%2Fcb%2Fexample.com" }'
```
別リージョンを利用している場合は `us.authlete.com` をご利用のクラスターホスト（`eu.authlete.com`、`jp.authlete.com` など）に置き換えてください。サービスアクセストークンの取得方法は[認証](/ja/get-started/concepts/authentication)を参照してください。
### 主なリクエストパラメーター
リクエストパラメーターの正確な構成は API ごとに異なり、サービスがサポートする OAuth/OIDC 仕様にも依存するため、完全には一般化できません。呼び出す API の [API リファレンス](/api-reference)を必ず確認してください。そのうえで、多くの Core API に共通して登場する主なリクエストパラメーターは次のとおりです。
| パラメーター | 説明 |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parameters` | エンドポイントがクライアントから受け取ったリクエストをそのまま渡します。認可エンドポイントではクエリ文字列、トークンエンドポイントでは `application/x-www-form-urlencoded` のリクエストボディです。 |
| `clientId` | クライアント ID。クライアントが `client_secret_basic` で認証する場合は、トークンエンドポイントへのリクエストの `Authorization: Basic` ヘッダーから取り出します。 |
| `clientSecret` | クライアントシークレット。同様に `Authorization: Basic` ヘッダーから取り出します。 |
| `clientCertificate` | mutual TLS 接続のクライアント証明書。mTLS クライアント認証や証明書バインドアクセストークン（[RFC 8705](https://www.rfc-editor.org/rfc/rfc8705)）をサポートする場合に必要です。 |
| `ticket` | 2 段階呼び出しの 1 つ目の API（[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) など）が返すチケット。2 つ目の API（[/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) など）に渡します。[2 段階の API 呼び出し](/ja/get-started/concepts/two-step-api-calls)を参照してください。 |
| `token` | 検査対象のアクセストークン。[/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request) や [/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request) などで使用します。 |
| `subject` | サーバーが認証したエンドユーザーの一意な識別子。[/auth/authorization/issue](/api-reference/authorization-endpoint/issue-authorization-response) などの発行系 API に渡します。 |
サポートする仕様を追加すると、それに応じてパラメーターも増えます。たとえば DPoP（[RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)）をサポートする場合、トークンリクエストやイントロスペクションリクエストに `dpop`、`htm`、`htu` が加わります。
## クライアントからのリクエストパラメーターはそのまま渡す
認可サーバーは、認可エンドポイントやトークンエンドポイントで受け取ったパラメーターを、対応する Authlete API に**そのまま渡すことが期待されます。原則として、事前に変更・加工してはいけません**。
たとえば認可リクエストの `scope` パラメーターの値を確認したい場合でも、[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API を呼び出す前に検証する必要はありません。クエリ文字列全体を `parameters` フィールドの値としてそのまま渡してください。Authlete がリクエストを検証し、検証済みのスコープ値をレスポンスで返すので、認可サーバーはそれを安全に利用できます。
[/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) や [/auth/token](/api-reference/token-endpoint/process-token-request) の呼び出し前に独自の検証・加工処理を実装することにはリスクがあります。Authlete のプロトコル処理やエラーチェックを活用できなくなり、最悪の場合、認可サーバーが OAuth 2.0 / OpenID Connect に非準拠となるおそれがあります。
## レスポンス形式
Core API のレスポンスは次のフィールドを共通して持ちます。
| フィールド | 説明 |
| ----------------- | ---------------------------------------------------------- |
| `resultCode` | 処理結果を識別するコード（例：`A004001`）。ログ記録やトラブルシューティングに利用します。 |
| `resultMessage` | 処理結果を説明する、人間が読めるメッセージ。 |
| `action` | サーバーが次に取るべきアクション。**実装はこのフィールドで分岐しなければなりません。** |
| `responseContent` | クライアントへのレスポンス構築に使う内容。JSON ボディやエラーパラメーター付きのリダイレクト URI などです。 |
`action` フィールドは Core API のプログラミングモデルの中核です。クライアントにどのような HTTP レスポンスを返すべきか、あるいは次にどの Authlete API を呼ぶべきかを示します。詳細は[アクションハンドリング](/ja/get-started/concepts/action-handling)を参照してください。
`resultCode` を処理の分岐条件に使ってはいけません。結果コードは診断情報であり、認可サーバーの処理の分岐は `action` を利用することが推奨されます。