> ## 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. # Issue Authorization Response > This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. This API is supposed to be called from within the implementation of the authorization endpoint of the service in order to generate a successful response to the client application. The description of the `/auth/authorization` API describes the timing when this API should be called and the meaning of request parameters. See \[ISSUE] in `NO_INTERACTION`. The response from `/auth/authorization/issue` 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". 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 {responseContent} ``` 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. The HTTP status of the response returned to the client application should be "400 Bad Request" and the content type should be `application/json` although OAuth 2.0 specification does not mention the format of the error response. 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 {responseContent} ``` 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 should be "302 Found" with `Location` header. The value of `responseContent` is a redirect URI which contains (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: {responseContent} Cache-Control: no-store Pragma: no-cache ``` ## FORM When the value of `action` is `FORM`, it means that the response to the client application should be "200 OK" with an HTML which triggers redirection by JavaScript. This happens when the authorization request from the client contains `response_mode=form_post` request parameter. The value of `responseContent` is an HTML which satisfies the requirements of `response_mode=form_post`, 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 200 OK Content-Type: text/html;charset=UTF-8 Cache-Control: no-store Pragma: no-cache {responseContent} ``` ## OpenAPI ````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/auth/authorization/issue 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/issue: post: tags: - Authorization Endpoint summary: Issue Authorization Response description: > This API parses request parameters of an authorization request and returns necessary data for the authorization server implementation to process the authorization request further. operationId: auth_authorization_issue_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_issue_request' example: ticket: FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/authorization_issue_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/authorization_issue_response' example: resultCode: A040001 resultMessage: >- [A040001] The authorization request was processed successfully. accessTokenDuration: 0 accessTokenExpiresAt: 0 action: LOCATION authorizationCode: Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo responseContent: >- https://my-client.example.com/cb1?code=Xv_su944auuBgc5mfUnxXayiiQU9Z4-T_Yae_UfExmo&iss=https%3A%2F%2Fmy-service.example.com '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.issue({ serviceId: "", authorizationIssueRequest: { ticket: "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc", subject: "john", }, }); console.log(result); } run(); - lang: ruby label: Ruby (SDK) source: >- require 'authlete_ruby_sdk' Models = ::Authlete::Models s = ::Authlete::Client.new( bearer: '' ) res = s.authorization.issue_response(service_id: '', authorization_issue_request: Models::Components::AuthorizationIssueRequest.new( ticket: 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc', subject: 'john' )) unless res.authorization_issue_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.Issue(ctx, \"\", components.AuthorizationIssueRequest{\n Ticket: \"FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc\",\n Subject: \"john\",\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.AuthorizationIssueResponse != 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/issue \ -H 'Content-Type: application/json' \ -H 'Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F' \ -d '{ "ticket": "FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc", "subject": "john" }' - lang: java label: java source: | AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); AuthorizationIssueRequest req = new AuthorizationIssueRequest(); req.setTicket("FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc"); req.setSubject("john"); api.authorizationIssue(req); - lang: python source: | conf = ... api = AuthleteApiImpl(conf) req = AuthorizationIssueRequest() req.ticket = 'FFgB9gwb_WXh6g1u-UQ8ZI-d_k4B-o-cm7RkVzI8Vnc' req.subject = 'john' api.authorizationIssue(req) components: schemas: authorization_issue_request: type: object required: - ticket - subject properties: ticket: type: string description: | The ticket issued from Authlete `/auth/authorization` API. subject: type: string description: > The subject (= a user account managed by the service) who has granted authorization to the client application. authTime: type: integer format: int64 description: > The time when the authentication of the end-user occurred. Its value is the number of seconds from `1970-01-01`. acr: type: string description: >- The Authentication Context Class Reference performed for the end-user authentication. claims: type: string description: > The claims of the end-user (= pieces of information about the end-user) in JSON format. See [OpenID Connect Core 1.0, 5.1. Standard Claims](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims) for details about the format. properties: type: array items: $ref: '#/components/schemas/property' description: >- Extra properties to associate with an access token and/or an authorization code. scopes: type: array items: type: string description: > Scopes to associate with an access token and/or an authorization code. If a non-empty string array is given, it replaces the scopes specified by the original authorization request. sub: type: string description: > The value of the `sub` claim to embed in an ID token. If this request parameter is `null` or empty, the value of the `subject` request parameter is used as the value of the `sub` claim. idtHeaderParams: type: string description: > JSON that represents additional JWS header parameters for ID tokens that may be issued based on the authorization request. claimsForTx: type: string description: | Claim key-value pairs that are used to compute transformed claims. consentedClaims: type: array items: type: string description: | the claims that the user has consented for the client application to know. authorizationDetails: $ref: '#/components/schemas/authz_details' jwtAtClaims: type: string description: > Additional claims that are added to the payload part of the JWT access token. accessToken: type: string description: > The representation of an access token that may be issued as a result of the Authlete API call. accessTokenDuration: type: integer format: int64 description: > The duration (in seconds) of the access token that may be issued as a result of the Authlete API call. When this request parameter holds a positive integer, it is used as the duration of the access token in. In other cases, this request parameter is ignored. sessionId: type: string description: > The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. x-mint: metadata: description: >- The session ID of the user's authentication session. The specified value will be embedded in the ID token as the value of the `sid` claim. This parameter needs to be provided only if you want to support the [OpenID Connect Native SSO for Mobile Apps 1.0](https://openid.net/specs/openid-connect-native-sso-1_0.html) specification (a.k.a. "Native SSO"). To enable support for the Native SSO specification, the `nativeSsoSupported` property of your service must be set to `true`. content: > NOTE: When the response from the `/auth/authorization` API contains the `nativeSsoRequested` property with a value of `true`, the `sessionId` request parameter must be provided to the `/auth/authorization/issue` API. idTokenAudType: type: string description: > The type of the `aud` claim of the ID token being issued. Valid values are as follows. | Value | Description | | ----- | ----------- | | "array" | The type of the aud claim is always an array of strings. | | "string" | The type of the aud claim is always a single string. | | null | The type of the aud claim remains the same as before. | This request parameter takes precedence over the `idTokenAudType` property of the service. verifiedClaimsForTx: type: array items: type: string description: > Values of verified claims requested indirectly by "transformed claims". x-mint: metadata: description: >- Values of verified claims requested indirectly by "transformed claims". content: > A client application may request "transformed claims". Each of transformed claims uses an existing claim as input. As a result, to compute the value of a transformed claim, the value of the referenced existing claim is needed. This `verifiedClaimsForTx` request parameter has to be used to provide values of existing claims for computation of transformed claims. A response from the `/auth/authorization` API may include the `requestedVerifiedClaimsForTx` response parameter which is a list of verified claims that are referenced indirectly by transformed claims (cf. `requestedVerifiedClaimsForTx` in `/auth/authorization` API response). The authorization server implementation should prepare values of the verified claims listed in `requestedVerifiedClaimsForTx` and pass them as the value of this `verifiedClaimsForTx` request parameter. The following is an example of the value of this request parameter. ``` [ "{\"birthdate\":\"1970-01-23\",\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` The reason that this `verifiedClaimsForTx` property is an array is that the `"verified_claims"` property in the claims request parameter of an authorization request can be an array like below. ``` { "transformed_claims": { "nationality_usa": { "claim": "nationalities", "fn": [ [ "eq", "USA" ], "any" ] } }, "id_token": { "verified_claims": [ { "verification": { "trust_framework": { "value": "gold" } }, "claims": { "::18_or_above": null } }, { "verification": { "trust_framework": { "value": "silver" } }, "claims": { ":nationality_usa": null } } ] } } ``` For the example above, the value of this `verifiedClaimsForTx` property should be an array of size 2 and look like below. The first element is JSON including claims which have been verified under the trust framework `"gold"`, and the second element is JSON including claims which have been verified under the trust framework `"silver"`. ``` [ "{\"birthdate\":\"1970-01-23\"}", "{\"nationalities\":[\"DEU\",\"USA\"]}" ] ``` authorization_issue_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. accessToken: type: string description: > The newly issued access token. Note that an access token is issued from an authorization endpoint only when `response_type` contains token. accessTokenExpiresAt: type: integer format: int64 description: > The datetime at which the newly issued access token will expire. The value is represented in milliseconds since the Unix epoch (1970-01-01). accessTokenDuration: type: integer format: int64 description: | The duration of the newly issued access token in seconds. idToken: type: string description: > The newly issued ID token. Note that an ID token is issued from an authorization endpoint only when `response_type` contains `id_token`. authorizationCode: type: string description: > The newly issued authorization code. Note that an authorization code is issued only when `response_type` contains code. jwtAccessToken: type: string description: > The newly issued access token in JWT format. If the service is not configured to issue JWT-based access tokens, this property is always set to `null`. ticketInfo: $ref: '#/components/schemas/authorization_ticket_info' description: | The information about the ticket. property: type: object properties: key: type: string description: The key part. value: type: string description: The value part. hidden: type: boolean description: > The flag to indicate whether this property hidden from or visible to client applications. If `true`, this property is hidden from client applications. Otherwise, this property is visible to client applications. authz_details: type: object description: > The authorization details. This represents the value of the `authorization_details` request parameter in the preceding device authorization request which is defined in "OAuth 2.0 Rich Authorization Requests". properties: elements: type: array items: $ref: '#/components/schemas/authorization_details_element' description: | Elements of this authorization details. authorization_ticket_info: type: object properties: context: type: string description: | The arbitrary text attached to the ticket. 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. authorization_details_element: type: object required: - type properties: type: type: string description: > The type of this element. From _"OAuth 2.0 Rich Authorization Requests"_: _"The type of authorization data as a string. This field MAY define which other elements are allowed in the request. This element is REQUIRED."_ This property is always NOT `null`. locations: type: array items: type: string description: > The resources and/or resource servers. This property may be `null`. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the location of the resource or resource server. This is typically composed of URIs."_ This property may be `null`. actions: type: array items: type: string description: > The actions. From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of actions to be taken at the resource. The values of the strings are determined by the API being protected."_ This property may be `null`. dataTypes: type: array items: type: string description: > From _"OAuth 2.0 Rich Authorization Requests"_: _"An array of strings representing the kinds of data being requested from the resource."_ This property may be `null`. identifier: type: string description: > The identifier of a specific resource. From _"OAuth 2.0 Rich Authorization Requests"_: _"A string identifier indicating a specific resource available at the API."_ This property may be `null`. privileges: type: array items: type: string description: > The types or levels of privilege. From "OAuth 2.0 Rich Authorization Requests": _"An array of strings representing the types or levels of privilege being requested at the resource."_ This property may be `null`. otherFields: type: string description: > The RAR request in the JSON format excluding the pre-defined attributes such as `type` and `locations`. The content and semantics are specific to the deployment and the use case implemented. 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 ` 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. ````