Action Handling

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.

You NEVER use the value of resultCode as a condition of processing.

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: This page walks through the actions of the /auth/authorization 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 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.
`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.
`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 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.

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, /auth/userinfo, 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).
`CREATED`	/client/registration	A resource was created (e.g. dynamic client registration). Return `201 Created` with `responseContent`.
`UNAUTHORIZED`	/auth/userinfo, /auth/introspection	The presented token is invalid. Return `401 Unauthorized` with `responseContent` as the `WWW-Authenticate` header.
`INVALID_CLIENT`	/auth/token, /auth/revocation	Client authentication failed. Return `400` or `401` as described in the API reference.
`FORBIDDEN`	/auth/introspection, /auth/userinfo	The access token is valid but lacks the scopes (or resources) required for the request. Return `403 Forbidden`.
`NOT_FOUND`	/gm	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	Your server must perform its own validation (user credentials, subject token, assertion) before deciding to issue tokens — see Two-Step API Calls.

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.

Introduction to Authlete

Quickstarts

Concepts

Developer Resources

Tools

Actions of /auth/authorization

Mapping Actions to HTTP Responses

Actions That Need More Steps

Representative Actions in Other APIs

​Actions of /auth/authorization

​Mapping Actions to HTTP Responses

​Actions That Need More Steps

​Representative Actions in Other APIs

Actions of /auth/authorization

Mapping Actions to HTTP Responses

Actions That Need More Steps

Representative Actions in Other APIs