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

# Fail Authorization Request

> This API generates a content of an error authorization response that the authorization server implementation returns to the client application.

<Accordion title="Full description" defaultOpen={false}>
  This API is supposed to be called from within the implementation of the authorization endpoint of the service
  in order to generate an error response to the client application.
  The description of the `/auth/authorization` API describes the timing when this API should be called.
  The response from `/auth/authorization/fail` 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 the request from the authorization
  server implementation was wrong or that an error occurred in Authlete.
  In either case, from the viewpoint of the client application, it is an error on the server side.
  Therefore, the service implementation should generate a response to the client application with
  HTTP status of "500 Internal Server Error". Authlete recommends `application/json` as the content type.
  The value of `responseContent` is a JSON string which describes the error, so it can be used
  as the entity body of the response.

  ***

  The following illustrates the response which the service implementation should generate and return
  to the client application.

  ```
  HTTP/1.1 500 Internal Server Error
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache
  &#123;responseContent&#125;
  ```

  The endpoint implementation may return another different response to the client application since
  "500 Internal Server Error" is not required by OAuth 2.0.

  ## BAD\_REQUEST

  When the value of `action` is `BAD_REQUEST`, it means that the ticket is no longer valid (deleted
  or expired) and that the reason of the invalidity was probably due to the end-user's too-delayed
  response to the authorization UI.
  A response with HTTP status of "400 Bad Request" should be returned to the client application and
  Authlete recommends `application/json` as the content type.
  The value of `responseContent` is a JSON string which describes the error, so it can be used
  as the entity body of the response.

  ***

  The following illustrates the response which the service implementation should generate and return
  to the client application.

  ```
  HTTP/1.1 400 Bad Request
  Content-Type: application/json
  Cache-Control: no-store
  Pragma: no-cache
  &#123;responseContent&#125;
  ```

  The endpoint implementation may return another different response to the client application since
  "400 Bad Request" is not required by OAuth 2.0.

  ## LOCATION

  When the value of `action` is `LOCATION`, it means that the response to the client application must
  be "302 Found" with Location header.
  The parameter responseContent contains a redirect URI with (1) an authorization code, an ID token
  and/or an access token (on success) or (2) an error code (on failure), so it can be used as the
  value of `Location` header.

  ***

  The following illustrates the response which the service implementation must generate and return
  to the client application.

  ```
  HTTP/1.1 302 Found
  Location: &#123;responseContent&#125;
  Cache-Control: no-store
  Pragma: no-cache
  ```

  ## FORM

  When the value of `action` is `FORM`, it means that the response to the client application must be 200 OK
  with an HTML which triggers redirection by JavaScript.
  This happens when the authorization request from the client application contained `response_mode=form_post`.
  The value of `responseContent` is an HTML which can be used as the entity body of the response.

  ***

  The following illustrates the response which the service implementation must generate and return
  to the client application.

  ```
  HTTP/1.1 200 OK
  Content-Type: text/html;charset=UTF-8
  Cache-Control: no-store
  Pragma: no-cache
  &#123;responseContent&#125;
  ```
</Accordion>


## OpenAPI

````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/auth/authorization/fail
openapi: 3.0.3
info:
  title: Authlete API
  description: ''
  version: 3.0.16
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - description: 🇺🇸 US Cluster
    url: https://us.authlete.com
  - description: 🇯🇵 Japan Cluster
    url: https://jp.authlete.com
  - description: 🇪🇺 Europe Cluster
    url: https://eu.authlete.com
  - description: 🇧🇷 Brazil Cluster
    url: https://br.authlete.com
security:
  - bearer: []
tags:
  - name: Service Management
    description: >-
      API endpoints for managing services, including creation, update, and
      deletion of services.
    x-tag-expanded: false
  - name: Client Management
    description: >-
      API endpoints for managing OAuth clients, including creation, update, and
      deletion of clients.
    x-tag-expanded: false
  - name: Authorization Endpoint
    description: API endpoints for implementing OAuth 2.0 Authorization Endpoint.
    x-tag-expanded: false
  - name: Pushed Authorization Endpoint
    description: >-
      API endpoints for implementing OAuth 2.0 Pushed Authorization Requests
      (PAR).
    x-tag-expanded: false
  - name: Token Endpoint
    description: API endpoints for implementing OAuth 2.0 Token Endpoint.
    x-tag-expanded: false
  - name: Token Operations
    description: >-
      API endpoints for various token related operations, including creating,
      revoking and deleting access_tokens with specified scopes.
    x-tag-expanded: false
  - name: Introspection Endpoint
    description: API endpoints for implementing OAuth 2.0 Introspection Endpoint.
    x-tag-expanded: false
  - name: Revocation Endpoint
    description: API endpoint for implementing OAuth 2.0 Revocation Endpoint.
    x-tag-expanded: false
  - name: UserInfo Endpoint
    description: API endpoints for implementing OpenID Connect UserInfo Endpoint.
    x-tag-expanded: false
  - name: JWK Set Endpoint
    description: API endpoints for to generate JSON Web Key Set (JWKS) for a service.
    x-tag-expanded: false
  - name: Discovery Endpoint
    description: API endpoints for implementing OpenID Connect Discovery.
    x-tag-expanded: false
  - name: Configuration Endpoint
    description: API endpoint for accessing configuration settings for a service.
    x-tag-expanded: false
  - name: Dynamic Client Registration
    description: API endpoints for implementing OAuth 2.0 Dynamic Client Registration.
    x-tag-expanded: false
  - name: CIBA
    description: >-
      API endpoints for implementing Client-Initiated Backchannel Authentication
      (CIBA).
    x-tag-expanded: false
  - name: Grant Management Endpoint
    description: >-
      API endpoint for implementing OAuth 2.0 grants, including grant management
      actions like updating and revoking grants.
    x-tag-expanded: false
  - name: Jose Object
    description: API endpoints for JOSE objects.
    x-tag-expanded: false
  - name: Device Flow
    description: API endpoints for implementing OAuth 2.0 Device Flow
    x-tag-expanded: false
  - name: Federation Endpoint
    description: API endpoints for implementing OpenID Federation using Authlete.
    x-tag-expanded: false
  - name: Verifiable Credential Issuer
    description: >-
      API endpoints for implementing and running a Verifiable Credential Issuer
      (VCI).
    x-tag-expanded: false
  - name: Hardware Security Key
    description: API endpoints for managing hardware security keys (HSK).
    x-tag-expanded: false
  - name: Utility Endpoints
    description: API endpoints for various utility operations.
    x-tag-expanded: false
  - name: Native SSO
    description: API endpoints for Native SSO
    x-tag-expanded: false
paths:
  /api/{serviceId}/auth/authorization/fail:
    post:
      tags:
        - Authorization Endpoint
      summary: Fail Authorization Request
      description: >
        This API generates a content of an error authorization response that the
        authorization server implementation

        returns to the client application.
      operationId: auth_authorization_fail_api
      parameters:
        - in: path
          name: serviceId
          description: A service ID.
          schema:
            type: string
          required: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/authorization_fail_request'
            example:
              ticket: qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ
              reason: NOT_AUTHENTICATED
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/authorization_fail_request'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authorization_fail_response'
              example:
                resultCode: A004201
                resultMessage: >-
                  [A004201] The authorization request from the service does not
                  contain 'parameters' parameter.
                action: BAD_REQUEST
                responseContent: >-
                  {\"error_description\":\"[A004201] The authorization request
                  from the service does not contain 'parameters'
                  parameter.\",\"error\":\"invalid_request\",\"error_uri\":\"https://docs.authlete.com/#A004201\"}
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
        '403':
          $ref: '#/components/responses/403'
        '500':
          $ref: '#/components/responses/500'
      x-codeSamples:
        - lang: typescript
          label: Typescript (SDK)
          source: |-
            import { Authlete } from "@authlete/typescript-sdk";

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

            async function run() {
              const result = await authlete.authorization.fail({
                serviceId: "<id>",
                authorizationFailRequest: {
                  ticket: "qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ",
                  reason: "NOT_AUTHENTICATED",
                },
              });

              console.log(result);
            }

            run();
        - lang: ruby
          label: Ruby (SDK)
          source: >-
            require 'authlete_ruby_sdk'


            Models = ::Authlete::Models

            s = ::Authlete::Client.new(
              bearer: '<YOUR_BEARER_TOKEN_HERE>'
            )

            res = s.authorization.fail_request(service_id: '<id>',
            authorization_fail_request:
            Models::Components::AuthorizationFailRequest.new(
              ticket: 'qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ',
              reason: Models::Components::AuthorizationFailRequestReason::NOT_AUTHENTICATED
            ))


            unless res.authorization_fail_response.nil?
              # handle response
            end
        - lang: go
          label: Go (SDK)
          source: "package main\n\nimport(\n\t\"context\"\n\t\"os\"\n\tauthlete \"github.com/authlete/authlete-go-sdk\"\n\t\"github.com/authlete/authlete-go-sdk/models/components\"\n\t\"log\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    s := authlete.New(\n        authlete.WithSecurity(os.Getenv(\"AUTHLETE_BEARER\")),\n    )\n\n    res, err := s.Authorization.Fail(ctx, \"<id>\", components.AuthorizationFailRequest{\n        Ticket: \"qA7wGybwArICpbUSutrf5Xc9-i1fHE0ySOHxR1eBoBQ\",\n        Reason: components.AuthorizationFailRequestReasonNotAuthenticated,\n    })\n    if err != nil {\n        log.Fatal(err)\n    }\n    if res.AuthorizationFailResponse != nil {\n        // handle response\n    }\n}"
      x-code-samples:
        - lang: shell
          label: curl
          source: >
            curl -v -X POST
            https://us.authlete.com/api/21653835348762/auth/authorization/fail \

            -H 'Content-Type: application/json' \

            -H 'Authorization: Bearer
            V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \

            -d '{ "ticket": "c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q",
            "reason": "NOT_AUTHENTICATED" }'
        - lang: java
          label: java
          source: |
            AuthleteConfiguration conf = ...;
            AuthleteApi api = AuthleteApiFactory.create(conf);

            AuthorizationFailRequest req = new AuthorizationFailRequest();
            req.setTicket("c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q");
            req.setReason(AuthorizationFailRequest.Reason.NOT_AUTHENTICATED);

            api.authorizationFail(req);
        - lang: python
          source: |
            conf = ...
            api = AuthleteApiImpl(conf)

            req = AuthorizationFailRequest()
            req.ticket = 'c4iy3TWGn74UMO7ihRl0ZS8OEUzV9axBlBbJbqxH-9Q'
            req.reason = AuthorizationFailReason.NOT_AUTHENTICATED

            api.authorizationFail(req)
components:
  schemas:
    authorization_fail_request:
      type: object
      required:
        - ticket
        - reason
      properties:
        ticket:
          type: string
          description: |
            The ticket issued from Authlete `/auth/authorization` API.
        reason:
          type: string
          enum:
            - UNKNOWN
            - NOT_LOGGED_IN
            - MAX_AGE_NOT_SUPPORTED
            - EXCEEDS_MAX_AGE
            - DIFFERENT_SUBJECT
            - ACR_NOT_SATISFIED
            - DENIED
            - SERVER_ERROR
            - NOT_AUTHENTICATED
            - ACCOUNT_SELECTION_REQUIRED
            - CONSENT_REQUIRED
            - INTERACTION_REQUIRED
            - INVALID_TARGET
          description: >
            The reason of the failure of the authorization request.

            For more details, see [NO_INTERACTION] in the description of
            `/auth/authorization` API.
        description:
          type: string
          description: |
            The custom description about the authorization failure.
    authorization_fail_response:
      type: object
      properties:
        resultCode:
          type: string
          description: The code which represents the result of the API call.
        resultMessage:
          type: string
          description: A short message which explains the result of the API call.
        action:
          type: string
          enum:
            - INTERNAL_SERVER_ERROR
            - BAD_REQUEST
            - LOCATION
            - FORM
          description: >-
            The next action that the authorization server implementation should
            take.
        responseContent:
          type: string
          description: >
            The content that the authorization server implementation is to
            return to the client application.

            Its format varies depending on the value of `action` parameter.
    result:
      type: object
      properties:
        resultCode:
          type: string
          description: The code which represents the result of the API call.
        resultMessage:
          type: string
          description: A short message which explains the result of the API call.
  responses:
    '400':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001201
            resultMessage: '[A001201] /auth/authorization, TLS must be used.'
    '401':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001202
            resultMessage: '[A001202] /auth/authorization, Authorization header is missing.'
    '403':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001215
            resultMessage: >-
              [A001215] /auth/authorization, The client (ID = 26837717140341) is
              locked.
    '500':
      description: ''
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/result'
          example:
            resultCode: A001101
            resultMessage: '[A001101] /auth/authorization, Authlete Server error.'
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >
        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.

````