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

# Action Handling

> How to branch on the action field in Core API responses and map each action to the HTTP response your authorization server returns.

Most Core API responses include an `action` field. The principle of implementing an authorization server with Authlete is simple: call a Core API, parse the response, check the value of `action`, and process accordingly.

<Warning>
  You **NEVER** use the value of `resultCode` as a condition of processing.
</Warning>

Each Core API defines its own set of actions, but the values fall into two patterns — actions that map directly to an HTTP response to the client, and actions that require a second Authlete API call:

```mermaid theme={null}
flowchart TD
    Start(["Response from a Core API"]) --> D{"action"}

    D -->|"Direct response (e.g. LOCATION)"| L["HTTP response<br/>built from responseContent"]

    D -->|"Two-step call (e.g. INTERACTION)"| Work["Server-side work<br/>(e.g. authenticate user)"]
    Work --> Next["Call the next Authlete API"]
    Next -.->|response carries another action| D
```

This page walks through the actions of the [/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API to show how the model works, then introduces **representative** actions you will encounter in other Core APIs — the lists on this page are not exhaustive, so always consult the API reference of the API you are calling.

## Actions of /auth/authorization

A response from the [/auth/authorization](/api-reference/authorization-endpoint/process-authorization-request) API contains one of the following values in the `action` field:

| Action                  | Meaning                                                                          | What your server does (example)                                                                       |
| ----------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `INTERACTION`           | The authorization request is valid and user interaction is required.             | Continue with a second API call — see [Two-Step API Calls](/get-started/concepts/two-step-api-calls). |
| `NO_INTERACTION`        | The request is valid and requires no user interaction (e.g. `prompt=none`).      | Continue with a second API call — see [Two-Step API Calls](/get-started/concepts/two-step-api-calls). |
| `LOCATION`              | A redirect response should be returned.                                          | Return `302 Found` with `responseContent` as the `Location` header.                                   |
| `FORM`                  | A form-post response should be returned.                                         | Return `200 OK` with `responseContent` (an HTML form) as the body.                                    |
| `BAD_REQUEST`           | The authorization request is invalid.                                            | Return `400 Bad Request` with `responseContent` as the body.                                          |
| `INTERNAL_SERVER_ERROR` | An error occurred on the Authlete side or the request to Authlete was malformed. | Return `500 Internal Server Error` with `responseContent` as the body.                                |

Besides `action`, the response also carries the information your authorization server needs to build the authentication and consent page — such as the client's display information and the requested scopes and claims. See the [API Reference](/api-reference/authorization-endpoint/process-authorization-request) for the full response schema.

## Mapping Actions to HTTP Responses

Most actions correspond one-to-one to an HTTP response your server returns to the client, built from `responseContent`. For example, when the response from the Authlete Core API contains `action` of `BAD_REQUEST`, your authorization server returns a response like the following to the client:

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

(responseContent)
```

And when `action` is `LOCATION`:

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

## Actions That Need More Steps

`INTERACTION` and `NO_INTERACTION` — along with grant-processing actions such as `PASSWORD`, `TOKEN_EXCHANGE`, and `JWT_BEARER` — cannot be completed by returning a single HTTP response. Your server needs to do its own work, such as authenticating the user and obtaining consent, and then call a second Authlete API to finish the processing. This pattern is explained in [Two-Step API Calls](/get-started/concepts/two-step-api-calls).

## Representative Actions in Other APIs

Other Core APIs follow the same convention with their own action sets. The following are representative actions — not an exhaustive list:

| Action                                     | Examples of APIs                                                                                                                                                                     | What your server does (example)                                                                                                                                                                                                                              |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `OK`                                       | [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request), [/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request), many others | The request was processed successfully. Typically return `200 OK` with `responseContent`, or proceed to the next step (for `/auth/userinfo`, gather claim values and call [/auth/userinfo/issue](/api-reference/userinfo-endpoint/issue-userinfo-response)). |
| `CREATED`                                  | [/client/registration](/api-reference/client-management/create-client)                                                                                                               | A resource was created (e.g. dynamic client registration). Return `201 Created` with `responseContent`.                                                                                                                                                      |
| `UNAUTHORIZED`                             | [/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request), [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request)              | The presented token is invalid. Return `401 Unauthorized` with `responseContent` as the `WWW-Authenticate` header.                                                                                                                                           |
| `INVALID_CLIENT`                           | [/auth/token](/api-reference/token-endpoint/process-token-request), [/auth/revocation](/api-reference/revocation-endpoint/process-revocation-request)                                | Client authentication failed. Return `400` or `401` as described in the API reference.                                                                                                                                                                       |
| `FORBIDDEN`                                | [/auth/introspection](/api-reference/introspection-endpoint/process-introspection-request), [/auth/userinfo](/api-reference/userinfo-endpoint/process-userinfo-request)              | The access token is valid but lacks the scopes (or resources) required for the request. Return `403 Forbidden`.                                                                                                                                              |
| `NOT_FOUND`                                | [/gm](/api-reference/grant-management-endpoint/process-grant-management-request)                                                                                                     | The target resource does not exist (e.g. the `grant_id` specified in a Grant Management request). Return `404 Not Found`.                                                                                                                                    |
| `PASSWORD`, `TOKEN_EXCHANGE`, `JWT_BEARER` | [/auth/token](/api-reference/token-endpoint/process-token-request)                                                                                                                   | Your server must perform its own validation (user credentials, subject token, assertion) before deciding to issue tokens — see [Two-Step API Calls](/get-started/concepts/two-step-api-calls).                                                               |

<Note>
  Newer APIs (e.g. `/vci/*`, `/gm`) distinguish where an error originates: `CALLER_ERROR` means the request from your implementation is wrong, while `AUTHLETE_ERROR` indicates an error inside Authlete.
</Note>