SUCCESS and ERROR.
+The response can have three possible states: SUCCESS, FAILEDand ERROR.
-SUCCESS: Indicates that the request was processed successfully and includes any state changes or modifications that should be applied.
+SUCCESS: Indicates that the request was processed successfully, including any state changes or modifications that need to be applied.
-ERROR: Indicates a failure in processing, accompanied by an error message that should be communicated to the application. This error message should adhere to OAuth 2.0 error response definitions to ensure compliance. However, it is your responsibility to ensure this compliance when extending the flow.
+FAILED: Represents a selective failure within the token flow due to validation logic or business rules enforced by your external service. A 400 (Client Error) response is returned to the application, incorporating the failure message provided by your external service. It is your responsibility to supply an OAuth 2.0-compliant failure message when extending the flow.
-!!! note
- Currently, ERROR responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.
+ERROR: Indicates a processing failure, typically caused by server-side issues. A 500 (Server Error) response is returned to the application.
#### Response for SUCCESS state:
@@ -376,9 +375,68 @@ Http Status Code: 200
!!! tip
Refer the [sample responses for successful access token updates]({{base_path}}/references/actions/pre-issue-access-token-action/sample-success-responses/) to learn how to construct success responses for different scenarios.
+#### Response for FAILED state:
+
+When the external service returns a 200 OK status code with a FAILED state, it means the service has intentionally opted to prevent access token issuance. This decision is based on specific validation logic or business rules defined by your application's requirements.
+
+The response body must be a JSON object containing the following properties:
+
+Http Status Code: 200
+
+| Property | +Description | +
|---|---|
| actionStatus | +Indicates the outcome of the request. For a failed operation, this should be set to |
+
| failureReason | +Provides the reason for failing to issue an access token. This value will be mapped to the error field in the response returned from the /oauth2/token endpoint.. |
+
| failureDescription | +Offers a detailed explanation of the failure. This value will be mapped to the error_description field in the |
+
ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating that the expected validations are not met or there is an issue processing the request.
+When the external service responds with an ERROR state, it can return an HTTP status code of 400, 401, or 500, indicating either a validation failure or an issue processing the request.
Http Status Code: 400, 401 or 500
@@ -396,8 +454,8 @@ Http Status Code: 400, 401 or 500
The error code, as specified in OAuth 2.0 error response definitions..
Describes the cause of the error..
ERROR responses are not communicated back to the client, but this functionality is planned for inclusion by end October 2024.
+If the external service returns an error response (either defined or undefined) or fails to respond entirely, it will be treated as an error in executing the action. In any of these cases, the application that initiated the token request will receive a 500 Internal Server Error.
+
+Below is an example of an error response returned by the service implementing the pre issue access token action.
+
+Response from external service:
+```http
+HTTP/1.1 500
+Content-Type: application/json
+
+{
+ "actionStatus": "ERROR",
+ "errorMessage": "Server error",
+ "errorDescription": "Error while processing request."
+}
+```
+
+This will result in the following error response being sent to the application that initiated the token request.
-If the defined error response is not received, or if the external service fails to respond, this is identified as an error in executing the action. In such cases, the flow will proceed as if the action was not applied, ensuring that the process continues without disruption.
+Error response to the application:
+```http
+HTTP/1.1 500
+Content-Type: application/json
+
+{
+ "error":”server_error",
+ "error_description": "Internal Server Error."
+}
+
+```
+
+!!! note
+ Currently, the errorMessage or errorDescription from the external service’s ERROR response is not directly included in the error response sent back to the application.