Skip to main content
POST
/
api
/
{serviceId}
/
backchannel
/
authentication
/
fail
Typescript (SDK)
import { Authlete } from "@authlete/typescript-sdk";

const authlete = new Authlete({
  bearer: process.env["AUTHLETE_BEARER"] ?? "",
});

async function run() {
  const result = await authlete.ciba.fail({
    serviceId: "<id>",
    backchannelAuthenticationFailRequest: {
      ticket: "<value>",
      reason: "MISSING_USER_CODE",
    },
  });

  console.log(result);
}

run();
{
  "resultCode": "A185001",
  "resultMessage": "[A185001] Successfully generated an error response for the backchannel authentication request.",
  "action": "FORBIDDEN",
  "responseContent": "{\\\"error\\\":\\\"access_denied\\\"}"
}
This API is supposed to be called from within the implementation of the backchannel authentication endpoint of the service in order to generate an error response to the client application. The response from /backchannel/authentication/fails API has some parameters. Among them, it is action parameter that the authorization server implementation should check first because it denotes the next action that the authorization server implementation should take. According to the value of action, the authorization server implementation must take the steps described below.

​
INTERNAL_SERVER_ERROR

When the value of action is INTERNAL_SERVER_ERROR, it means that (1) the reason request parameter of the API call was SERVER_ERROR, (2) an error occurred on Authlete side, or (3) the request parameters of the API call were wrong. In this case, the authorization server implementation should return a “500 Internal Server Error” response to the client application. However, in most cases, commercial implementations prefer to use other HTTP status code than 5xx.

​
BAD_REQUEST

When the value of action is BAD_REQUEST, the authorization server implementation should return a “400 Bad Request” response to the client application.

​
FORBIDDEN

When the value of action is FORBIDDEN, it means that the reason request parameter of the API call was ACCESS_DENIED. In this case, the backchannel authentication endpoint of the authorization server implementation should return a “403 Forbidden” response to the client application.

Authorizations

​
Authorization
string
header
required

Authenticate every request with a Service Access Token or Organization Token. Set the token value in the Authorization: Bearer <token> header.

Service Access Token: Scoped to a single service. Use when automating service-level configuration or runtime flows.

Organization Token: Scoped to the organization; inherits permissions across services. Use for org-wide automation or when managing multiple services programmatically.

Both token types are issued by the Authlete console or provisioning APIs.

Path Parameters

​
serviceId
string
required

A service ID.

Body

​
ticket
string
required

The ticket which should be deleted on a call of Authlete's /backchannel/authentication/fail API. This request parameter is not mandatory but optional. If this request parameter is given and the ticket belongs to the service, the specified ticket is deleted from the database. Giving this parameter is recommended to clean up the storage area for the service.

​
reason
enum<string>
required

The reason of the failure of the backchannel authentication request. This request parameter is not mandatory but optional. However, giving this parameter is recommended. If omitted, SERVER_ERROR is used as a reason.

Available options:
ACCESS_DENIED,
EXPIRED_LOGIN_HINT_TOKEN,
INVALID_BINDING_MESSAGE,
INVALID_TARGET,
INVALID_USER_CODE,
MISSING_USER_CODE,
SERVER_ERROR,
UNAUTHORIZED_CLIENT,
UNKNOWN_USER_ID
​
errorDescription
string

The description of the error. This corresponds to the error_description property in the response to the client.

​
errorUri
string

The URI of a document which describes the error in detail. If this optional request parameter is given, its value is used as the value of the error_uri property.

Response

​
resultCode
string

The code which represents the result of the API call.

​
resultMessage
string

A short message which explains the result of the API call.

​
action
enum<string>

The next action that the authorization server implementation should take.

Available options:
INTERNAL_SERVER_ERROR,
BAD_REQUEST,
FORBIDDEN
​
responseContent
string

The content that the authorization server implementation is to return to the client application. Its format varies depending on the value of action parameter.