Skip to main content
Some actions cannot be completed in a single API call. When the /auth/authorization API returns action=INTERACTION, your authorization server must authenticate the user and obtain consent before the authorization request can be answered — and that answer is produced by a second Authlete API call.

​
Two Types of Authorization Endpoint APIs

The Authorization Endpoint APIs consist of two types:
  1. An API that interprets the authorization request and provides the information needed for the next step, such as end-user authentication:
  2. APIs that issue tokens or codes, or return errors:
The typical flow for action=INTERACTION looks like this: If the user cancels or authentication fails, your server calls /auth/authorization/fail instead, and Authlete builds the appropriate error response for the client. Note that the response of the second API call also contains an action — handle it exactly as described in Action Handling.

​
The Ticket

The two API calls are linked by a ticket. The /auth/authorization API returns a ticket in its response, and /auth/authorization/issue or /auth/authorization/fail receives the ticket to complete the processing. Properties of the ticket:
  • A ticket expires in 24 hours. Expired tickets are deleted from Authlete’s database.
  • A ticket can be used only once. It is removed right after /auth/authorization/issue or /auth/authorization/fail successfully processes a request including it.
  • Using a ticket that has already been used or expired results in an error like this:
[A041202] There is no entity having the ticket specified
in the /api/auth/authorization/issue request (ticket = {Ticket}).
Tickets are designed to be used only between your authorization server and the Authlete server. Do not expose them to user agents such as web browsers — for example, never use a ticket to manage browser sessions.

​
The Same Model in Other APIs

The userinfo endpoint is a good example of the same model. The /auth/userinfo API validates the access token presented by the client and returns an action. When the action is OK, your server gathers the end-user’s claim values and calls /auth/userinfo/issue to build the userinfo response — Authlete formats it as plain JSON or as a signed/encrypted JWT according to the client’s configuration. The userinfo endpoint does not use a ticket; here the access token itself carries the context between the two calls.
The token endpoint also has two-step variants: when your service supports the Resource Owner Password Credentials grant, the /auth/token API returns action=PASSWORD, and your server validates the end-user’s credentials before calling /auth/token/issue or /auth/token/fail. The same pattern applies to TOKEN_EXCHANGE (RFC 8693) and JWT_BEARER (RFC 7523), where your server validates the subject token or assertion.
Once you understand the action-based model and the two-step pattern, every Core API follows naturally from its API reference.