openapi: 3.0.3 info: title: Authlete Authorization Endpoint CIBA API description: "Welcome to the **Authlete API documentation**. Authlete is an **API-first service** where every aspect of the \nplatform is configurable via API. This documentation will help you authenticate and integrate with Authlete to \nbuild powerful OAuth 2.0 and OpenID Connect servers.\n\nAt a high level, the Authlete API is grouped into two categories:\n\n- **Management APIs**: Enable you to manage services and clients.\n- **Runtime APIs**: Allow you to build your own Authorization Servers or Verifiable Credential (VC) issuers.\n\n## \U0001F310 API Servers\n\nAuthlete is a global service with clusters available in multiple regions across the world:\n\n- \U0001F1FA\U0001F1F8 **US**: `https://us.authlete.com`\n- \U0001F1EF\U0001F1F5 **Japan**: `https://jp.authlete.com`\n- \U0001F1EA\U0001F1FA **Europe**: `https://eu.authlete.com`\n- \U0001F1E7\U0001F1F7 **Brazil**: `https://br.authlete.com`\n\nOur customers can host their data in the region that best meets their requirements.\n\n## \U0001F511 Authentication\n\nAll API endpoints are secured using **Bearer token authentication**. You must include an access token in every request:\n\n```\nAuthorization: Bearer YOUR_ACCESS_TOKEN\n```\n\n### Getting Your Access Token\n\nAuthlete supports two types of access tokens:\n\n**Service Access Token** - Scoped to a single service (authorization server instance)\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to your service → **Settings** → **Access Tokens**\n3. Click **Create Token** and select permissions (e.g., `service.read`, `client.write`)\n4. Copy the generated token\n\n**Organization Token** - Scoped to your entire organization\n\n1. Log in to [Authlete Console](https://console.authlete.com)\n2. Navigate to **Organization Settings** → **Access Tokens**\n3. Click **Create Token** and select org-level permissions\n4. Copy the generated token\n\n> ⚠️ **Important Note**: Tokens inherit the permissions of the account that creates them. Service tokens can only \n> access their specific service, while organization tokens can access all services within your org.\n\n### Token Security Best Practices\n\n- **Never commit tokens to version control** - Store in environment variables or secure secret managers\n- **Rotate regularly** - Generate new tokens periodically and revoke old ones\n- **Scope appropriately** - Request only the permissions your application needs\n- **Revoke unused tokens** - Delete tokens you're no longer using from the console\n\n### Quick Test\n\nVerify your token works with a simple API call:\n\n```bash\ncurl -X GET https://us.authlete.com/api/service/get/list \\\n -H \"Authorization: Bearer YOUR_ACCESS_TOKEN\"\n```\n\n## \U0001F393 Tutorials\n\nIf you're new to Authlete or want to see sample implementations, these resources will help you get started:\n\n- [Getting Started with Authlete](https://www.authlete.com/developers/getting_started/)\n- [From Sign-Up to the First API Request](https://www.authlete.com/developers/tutorial/signup/)\n\n## \U0001F6E0 Contact Us\n\nIf you have any questions or need assistance, our team is here to help:\n\n- [Contact Page](https://www.authlete.com/contact/)\n" 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: CIBA description: API endpoints for implementing Client-Initiated Backchannel Authentication (CIBA). x-tag-expanded: false paths: /api/{serviceId}/backchannel/authentication: post: summary: Process Backchannel Authentication Request description: 'This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further. ' x-mint: metadata: description: This API parses request parameters of a [backchannel authentication request](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_request) and returns necessary data for the authorization server implementation to process the backchannel authentication request further. content: "\nThis API is supposed to be called from within the implementation of the [backchannel authentication\nendpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint)\nof the service. The endpoint implementation must extract the request parameters from the\nbackchannel authentication request from the client application and pass them as the value of parameters\nrequest parameter for Authlete's `/backchannel/authentication` API.\nThe value of parameters is the entire entity body (which is formatted in `application/x-www-form-urlencoded`)\nof the request from the client application.\nThe following code snippet is an example in JAX-RS showing how to extract request parameters from\nthe backchannel authentication request.\n```java\n@POST\n@Consumes(MediaType.APPLICATION_FORM_URLENCODED)\npublic Response post(String parameters)\n{\n// 'parameters' is the entity body of the backchannel authentication request.\n......\n}\n```\nThe endpoint implementation does not have to parse the request parameters from the client application\nbecause Authlete's `/backchannel/authentication` API does it.\nThe response from `/backchannel/authentication` API has various parameters. Among them, it is `action`\nparameter that the authorization server implementation should check first because it denotes the\nnext action that the authorization server implementation should take. According to the value of\n`action`, the service implementation must take the steps described below.\n\n## INTERNAL_SERVER_ERROR\n\nWhen the value of `action` is `INTERNAL_SERVER_ERROR`, it means that the request from the authorization\nserver implementation was wrong or that an error occurred in Authlete.\nIn either case, from the viewpoint of the client application, it is an error on the server side.\nTherefore, the service implementation should generate a response to the client application with\nHTTP status of \"500 Internal Server Error\" and `application/json`.\nThe value of `responseContent` is a JSON string which describes the error, so it can be used\nas the entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation should generate and return\nto the client application.\n```\nHTTP/1.1 500 Internal Server Error\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\n\n## BAD_REQUEST\n\nWhen the value of `action` is `BAD_REQUEST`, it means that the request from the client application\nis invalid.\nThe authorization server implementation should generate a response to the client application with\n\"400 Bad Request\" and `application/json`.\nThe value of `responseContent` is a JSON string which describes the error, so it can be used as\nthe entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation should generate and return\nto the client application.\n```\nHTTP/1.1 400 Bad Request\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\n\n## UNAUTHORIZED\n\nWhen the value of `action` is `UNAUTHORIZED`, it means that client authentication of the backchannel\nauthentication request failed. Note that client authentication is always required at the backchannel\nauthentication endpoint. This implies that public clients are not allowed to use the backchannel\nauthentication endpoint.\nThe authorization server implementation should generate a response to the client application with\n\"401 Unauthorized\" and `application/json`.\nThe value of `responseContent` is a JSON string which describes the error, so it can be used as\nthe entity body of the response.\n\n---\n\nThe following illustrates the response which the service implementation must generate and return\nto the client application.\n```\nHTTP/1.1 401 Unauthorized\nWWW-Authenticate: (challenge)\nContent-Type: application/json\nCache-Control: no-store\nPragma: no-cache\n{responseContent}\n```\n\n## USER_IDENTIFICATION\n\nWhen the value of `action` is `USER_IDENTIFICATION`, it means that the backchannel authentication\nrequest from the client application is valid. The authorization server implementation has to follow\nthe steps below.\n\n**[1] END-USER IDENTIFICATION**\n\nThe first step is to determine the subject (= unique identifier) of the end-user from whom the\n client application wants to get authorization.\n According to the CIBA specification, a backchannel authentication request contains one (and only\n one) of the `login_hint_token`, `id_token_hint` and `login_hint` request parameters as a hint\n by which the authorization server identifies the subject of an end-user.\n The authorization server implementation can know which hint is included in the backchannel authentication\n request by the `hintType` parameter. For example, when the value of the parameter `LOGIN_HINT`,\n it means that the backchannel authentication request contains the `login_hint` request parameter\n as a hint.\n The value of the `hint` parameter is the value of the hint. For example, when the value of the\n `hintType` parameter is `LOGIN_HINT`, The value of the `hint` parameter is the value of the `login_hint`\n request parameter.\n It is up to the authorization server implementation how to determine the subject of the end-user\n from the hint. Only when the `id_token_hint` request parameter is used, authorization server\n implementation can use the sub response parameter, which holds the value of the sub claim in the\n `id_token_hint` request parameter.\n\n**[2] END-USER IDENTIFICATION ERROR**\n\nThere are some cases where the authorization server implementation encounters an error during\n the user identification process. In any error case, the service implementation has to return an\n HTTP response with the error response parameter to the client application. The following is an\n example of such error responses.\n ```\n HTTP/1.1 400 Bad Request\n Content-Type: application/json\n Cache-Control: no-store\n Pragma: no-cache\n { \"error\":\"unknown_user_id\" }\n ```\n Authlete provides `/backchannel/authentication/fail` API that builds the response body (JSON)\n of an error response. However, because it is easy to build an error response manually, you may\n choose not to call the API. One good thing in using the API is that the API call can trigger\n deletion of the ticket which has been issued from Authlete's `/backchannel/authentication` API.\n If you don't call `/backchannel/authentication/fail` API, the ticket will continue to exist in\n the database until it is cleaned up by the batch program after the ticket expires.\n Possible error cases that the authorization server implementation itself has to handle are as\n follows. Other error cases have already been covered by `/backchannel/authentication` API.\n- `expired_login_hint_token`\nThe authorization server implementation detected that the hint presented by the `login_hint_token`\nrequest parameter has expired.\nNote that the format of `login_hint_token` is not described in the CIBA Core spec at all and\nso there is no consensus on how to detect expiration of `login_hint_token`. Interpretation\nof `login_hint_token` is left to each authorization server implementation.\n- `unknown_user_id`\nThe authorization server implementation could not determine the subject of the end-user by\nthe presented hint.\n- `unauthorized_client`\nThe authorization server implementation has custom rules to reject backchannel authentication\nrequests from some particular clients and found that the client which has made the backchannel\nauthentication request is one of the particular clients.\nNote that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` in\ncases where the client does not exist or client authentication has failed. Therefore, the\nauthorization server implementation will never have to use the error code `unauthorized_client`\nunless the server has intentionally implemented custom rules to reject backchannel authentication\nrequests based on clients.\n- `missing_user_code`\nThe authorization server implementation has custom rules to require that a backchannel authentication\nrequest include a user code for some particular users and found that the user identified by\nthe hint is one of the particular users.\nNote that `/backchannel/authentication` API does not return `action=USER_IDENTIFICATION` when\nboth the `backchannel_user_code_parameter_supported` metadata of the server and the\n`backchannel_user_code_parameter` metadata of the client are true and the backchannel authentication\nrequest does not include the user_code request parameter. In this case, `/backchannel/authentication`\nAPI returns action=BAD_REQUEST with JSON containing `\"error\":\"missing_user_code\"`. Therefore,\nthe authorization server implementation will never have to use the error code `missing_user_code`\nunless the server has intentionally implemented custom rules to require a user code based\non users even in the case where the `backchannel_user_code_parameter` metadata of the client\nwhich has made the backchannel authentication request is `false`.\n- `invalid_user_code`\nThe authorization server implementation detected that the presented user code is invalid.\nNote that the format of user_code is not described in the CIBA Core spec at all and so there\nis no consensus on how to judge whether a user code is valid or not. It is up to each authorization\nserver implementation how to handle user codes.\n- `invalid_binding_message`\nThe authorization server implementation detected that the presented binding message is invalid.\nNote that the format of binding_message is not described in the CIBA Core spec at all and\nso there is no consensus on how to judge whether a binding message is valid or not. It is\nup to each authorization server implementation how to handle binding messages.\n- `invalid_target`\nThe authorization server implementation rejects the requested target resources.\nThe error code invalid_target is from \"Resource Indicators for OAuth 2.0\". The specification\ndefines the resource request parameter. By using the parameter, client applications can request\ntarget resources that should be bound to the access token being issued. If the authorization\nserver wants to reject the request, call `/backchannel/authentication/fail` API with `INVALID_TARGET`.\n- `access_denined`\nThe authorization server implementation has custom rules to reject backchannel authentication\nrequests without asking the end-user and respond to the client as if the end-user had rejected\nthe request in some particular cases and found that the backchannel authentication request\nis one of the particular cases.\nThe authorization server implementation will never have to use the error code `access_denied`\nat this timing unless the server has intentionally implemented custom rules to reject backchannel\nauthentication requests without asking the end-user and respond to the client as if the end-user\nhad rejected the request.\n\n**[3] AUTH_REQ_ID ISSUE**\n\nIf the authorization server implementation has successfully determined the subject of the end-user,\n the next action is to return an HTTP response to the client application which contains `auth_req_id`.\n Authlete provides `/backchannel/authentication/issue` API which generates a JSON containing `auth_req_id`,\n so, your next action is (1) call the API, (2) receive the response from the API, (3) build a response\n to the client application using the content of the API response, and (4) return the response to\n the client application. See the description of `/backchannel/authentication/issue` API for details.\n\n**[4] END-USER AUTHENTICATION AND AUTHORIZATION**\n\nAfter sending a JSON containing `auth_req_id` back to the client application, the service implementation\n starts to communicate with an authentication device of the end-user. It is assumed that end-user\n authentication is performed on the authentication device and the end-user confirms the content of\n the backchannel authentication request and grants authorization to the client application if everything\n is okay. The authorization server implementation must be able to receive the result of the end-user\n authentication and authorization from the authentication device.\n How to communicate with an authentication device and achieve end-user authentication and authorization\n is up to each authorization server implementation, but the following request parameters of the backchannel\n authentication request should be taken into consideration in any implementation.\n- `acr_values`\nA backchannel authentication request may contain an array of ACRs (Authentication Context Class\nReferences) in preference order. If multiple authentication devices are registered for the end-user,\nthe authorization server implementation should take the ACRs into consideration when selecting\nthe best authentication device.\n- `scope`\nA backchannel authentication request always contains a list of scopes. At least, `openid` is\nincluded in the list (otherwise `/backchannel/authentication` API returns `action=BAD_REQUEST`).\nIt would be better to show the requested scopes to the end-user on the authentication device\nor somewhere appropriate.\nIf the scope request parameter contains `address`, `email`, `phone` and/or `profile`, they are\ninterpreted as defined in \"5.4. Requesting Claims using Scope Values of OpenID Connect Core 1.0\".\nThat is, they are expanded into a list of claim names. The claimNames parameter returns the expanded\nresult.\n- `binding_message`\nA backchannel authentication request may contain a binding message. It is a human readable identifier\nor message intended to be displayed on both the consumption device (client application) and the\nauthentication device.\n- `user_code`\nA backchannel authentication request may contain a user code. It is a secret code, such as password\nor pin, known only to the end-user but verifiable by the authorization server. The user code should\nbe used to authorize sending a request to the authentication device.\n\n**[5] END-USER AUTHENTICATION AND AUTHORIZATION COMPLETION**\n\nAfter receiving the result of end-user authentication and authorization, the authorization server\n implementation must call Authlete's `/backchannel/authentication/complete` API to tell Authlete\n the result and pass necessary data so that Authlete can generate an ID token, an access token and\n optionally a refresh token. See the description of the API for details.\n\n**[6] CLIENT NOTIFICATION**\n\nWhen the backchannel token delivery mode is either `ping` or `push`, the authorization server implementation\n must send a notification to the pre-registered notification endpoint of the client after the end-user\n authentication and authorization. In this case, the `action` parameter in a response from `/backchannel/authentication/complete`\n API is `NOTIFICATION`. See the description of `/backchannel/authentication/complete` API for details.\n\n**[7] TOKEN REQUEST**\n\nWhen the backchannel token delivery mode is either `ping` or `poll`, the client application will make\n a token request to the token endpoint to get an ID token, an access token and optionally a refresh\n token.\n A token request that corresponds to a backchannel authentication request uses `urn:openid:params:grant-type:ciba`\n as the value of the `grant_type` request parameter. Authlete's `/auth/token` API recognizes the\n grant type automatically and behaves properly, so the existing token endpoint implementation does\n not have to be changed to support CIBA.\n\n" parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_request' example: parameters: login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code clientId: '26862190133482' clientSecret: 8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_response' example: resultCode: A179001 resultMessage: '[A179001] The backchannel authentication request was processed successfully.' action: USER_IDENTIFICATION clientId: 26862190133482 clientIdAliasUsed: false clientName: My CIBA Client clientNotificationToken: my-client-notification-token deliveryMode: POLL hint: john hintType: LOGIN_HINT requestedExpiry: 0 scopes: - defaultEntry: false name: openid serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value ticket: Y1qeCf0A-JUz6caceaBfd2AaBYNZ-X-WGTP5Qv47cQI userCode: my-user-code userCodeRequired: false '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "parameters": "login_hint=john&scope=openid&client_notification_token=my-client-notification-token&user_code=my-user-code", "clientId": "26862190133482", "clientSecret":"8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationRequest req = new BackchannelAuthenticationRequest(); req.setParameters(...); req.setClientId("26862190133482"); req.setClientSecret("8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A"); api.backchannelAuthentication(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationRequest() req.parameters = ... req.clientId = ''26862190133482'' req.clientSecret = ''8J9pAEX6IQw7lYtYGsc_s9N4jlEz_DfkoCHIswJjFjfgKZX-nC4EvKtaHXcP9mHBfS7IU4jytjSZZpaK9UJ77A'' api.backchannelAuthentication(req) ' tags: - CIBA /api/{serviceId}/backchannel/authentication/issue: post: summary: Issue Backchannel Authentication Response description: 'This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) ' x-mint: metadata: description: This API prepares JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint) content: ' This API is supposed to be called from within the implementation of the backchannel authentication endpoint of the service in order to generate a successful response to the client application. The description of the `/backchannel/authentication` API describes the timing when this API should be called and the meaning of request parameters. See [AUTH_REQ_ID ISSUE] in `USER_IDENTIFICATION`. The response from `/backchannel/authentication/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. ```java @POST @Consumes(MediaType.APPLICATION_FORM_URLENCODED) public Response post(String parameters) { // ''parameters'' is the entity body of the backchannel authentication request. ...... } ``` The endpoint implementation does not have to parse the request parameters from the client application because Authlete''s `/backchannel/authentication` API does it. The response from `/backchannel/authentication` API has various 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 service 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" and `application/json`. 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} ``` ## INVALID_TICKET When the value of `action` is `INVALID_TICKET`, it means that the ticket included in the API call was invalid. For example, it does not exist or has expired. From a viewpoint of the client application, this is an error on the server side. Therefore, the authorization server implementation should generate a response to the client application with "500 Internal Server Error" and `application/json`. You can build an error response in the same way as shown in the description for the case of `INTERNAL_SERVER_ERROR`. ## OK When the value of `action` is `OK`, it means that Authlete has succeeded in preparing JSON that contains an `auth_req_id`. The JSON should be used as the response body of the response that is returned to the client from the backchannel authentication endpoint. `responseContent` contains the JSON. The following illustrates the response which the authorization server 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} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_issue_request' example: ticket: NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_issue_request' responses: '200': description: Backchannel authentication issued successfully content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_issue_response' example: resultCode: A183001 resultMessage: '[A183001] An auth_req_id was issued successfully.' action: OK authReqId: _mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE expiresIn: 3600 interval: 0 responseContent: '{\"auth_req_id\":\"_mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE\",\"interval\":0,\"expires_in\":3600}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_issue_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/issue \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationIssueRequest req = new BackchannelAuthenticationIssueRequest(); req.setTicket("NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q"); api.backchannelAuthenticationIssue(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationIssueRequest() req.ticket = ''NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q'' api.backchannelAuthenticationIssue(req) ' tags: - CIBA /api/{serviceId}/backchannel/authentication/fail: post: summary: Fail Backchannel Authentication Request description: 'The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint). ' x-mint: metadata: description: The API prepares JSON that contains an error. The JSON should be used as the response body of the response which is returned to the client from the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_endpoint). content: ' This API is supposed to be called from within the implementation of the [backchannel authentication endpoint](https://openid.net/specs/openid-client-initiated-backchannel-authentication-core-1_0.html#auth_backchannel_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. ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_fail_request' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_fail_request' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_fail_response' example: resultCode: A185001 resultMessage: '[A185001] Successfully generated an error response for the backchannel authentication request.' action: FORBIDDEN responseContent: '{\"error\":\"access_denied\"}' '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_fail_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/fail \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0", "reason": "ACCESS_DENIED" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationFailRequest req = new BackchannelAuthenticationFailRequest(); req.setTicket("holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0"); req.setReason(BackchannelAuthenticationFailRequest.Reason.ACCESS_DENIED); api.backchannelAuthenticationFail(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationFailRequest() req.ticket = ''holsZhINBhum6j6MYE4yZefHuQN_kd609veKCst31p0'' req.reason = BackchannelAuthenticationFailReason.ACCESS_DENIED api.backchannelAuthenticationFail(req) ' tags: - CIBA /api/{serviceId}/backchannel/authentication/complete: post: summary: Complete Backchannel Authentication description: 'This API returns information about what action the authorization server should take after it receives the result of end-user''s decision about whether the end-user has approved or rejected a client application''s request on the authentication device. ' x-mint: metadata: description: This API returns information about what action the authorization server should take after it receives the result of end-user's decision about whether the end-user has approved or rejected a client application's request on the authentication device. content: ' After the implementation of the backchannel authentication endpoint returns JSON containing an `auth_req_id` to the client, the authorization server starts a background process that communicates with the authentication device of the end-user. On the authentication device, end-user authentication is performed and the end-user is asked whether they give authorization to the client or not. The authorization server will receive the result of end-user authentication and authorization from the authentication device. After the authorization server receives the result from the authentication device, or even in the case where the server gave up receiving a response from the authentication device for some reasons, the server should call the `/backchannel/authentication/complete` API to tell Authlete the result. When the end-user was authenticated and authorization was granted to the client by the end-user, the authorization server should call the API with `result=AUTHORIZED`. In this successful case, the `subject` request parameter is mandatory. If the token delivery mode is `push`, the API will generate an access token, an ID token and optionally a refresh token. On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate tokens later. When the authorization server received the decision of the end-user from the authentication device and it indicates that the end-user has rejected to give authorization to the client, the authorization server should call the API with `result=ACCESS_DENIED`. In this case, if the token delivery mode is `push`, the API will generate an error response that contains the error response parameter and optionally the `error_description` and error_uri response parameters (if the `errorDescription` and `errorUri` request parameters have been given). On the other hand, if the token delivery mode is `poll` or `ping`, the API will just update the database record so that `/auth/token` API can generate an error response later. In any token delivery mode, the value of the error parameter will become `access_denied`. When the authorization server could not get the result of end-user authentication and authorization from the authentication device for some reasons, the authorization server should call the API with `result=TRANSACTION_FAILED`. In this error case, the API will behave in the same way as in the case of `ACCESS_DENIED`. The only difference is that `expired_token` is used as the value of the `error` parameter. The response from `/backchannel/authentication/complete` API has various 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 service implementation must take the steps described below. ## SERVER_ERROR When the value of `action` is `SERVER_ERROR`, it means either (1) that the request from the authorization server to Authlete was wrong, or (2) that an error occurred on Authlete side. When the backchannel token delivery mode is `ping` or `push`, `SERVER_ERROR` is used only when an error is detected before the record of the ticket (which is included in the API call to `/backchannel/authentication/complete`) is retrieved from the database successfully. If an error is detected after the record of the ticket is retrieved from the database, `NOTIFICATION` is used instead of `SERVER_ERROR`. When the backchannel token delivery mode is `poll`, `SERVER_ERROR` is used regardless of whether it is before or after the record of the ticket is retrieved from the database. ## NO_ACTION When the value of `action` is `NO_ACTION`, it means that the authorization server does not have to take any immediate action. `NO_ACTION` is returned when the backchannel token delivery mode is `poll`. In this case, the client will receive the final result at the token endpoint. ## NOTIFICATION When the value of `action` is `NOTIFICATION`, it means that the authorization server must send a notification to the client notification endpoint. According to the CIBA Core specification, the notification is an HTTP POST request whose request body is JSON and whose `Authorization` header contains the client notification token, which was included in the backchannel authentication request as the value of the `client_notification_token` request parameter, as a bearer token. When the backchannel token delivery mode is `ping`, the request body of the notification is JSON which contains the `auth_req_id` property only. When the backchannel token delivery mode is `push`, the request body will additionally contain an access token, an ID token and other properties. Note that when the backchannel token delivery mode is `poll`, a notification does not have to be sent to the client notification endpoint. In error cases, in the ping mode, however, the content of a notification is not different from the content in successful cases. That is, the notification contains the `auth_req_id` property only. The client will know the error when it accesses the token endpoint. On the other hand, in the `push` mode, in error cases, the content of a notification will include the `error` property instead of an access token and an ID token. The client will know the error by detecting that error is included in the notification. In any case, the value of `responseContent` is JSON which can be used as the request body of the notification. The client notification endpoint that the notification should be sent to the value of the `clientNotificationEndpoint` parameter. Likewise, the client notification token that the notification should include as a bearer token is the `clientNotificationToken` parameter. With these methods, the notification can be built like the following. ``` POST {clientNotificationEndpoint} HTTP/1.1 HOST: {The host of clientNotificationEndpoint} Authorization: Bearer {notificationToken} Content-Type: application/json {responseContent} ``` ' parameters: - in: path name: serviceId description: A service ID. required: true schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_complete_request' example: ticket: NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q result: AUTHORIZED subject: john application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/backchannel_authentication_complete_request' responses: '200': description: Backchannel authentication completed successfully content: application/json: schema: $ref: '#/components/schemas/backchannel_authentication_complete_response' example: resultCode: A198001 resultMessage: '[A198001] Successfully updated the database so that the token endpoint can generate tokens (mode = poll, result = AUTHORIZED).' accessTokenDuration: 0 action: NO_ACTION authReqId: _mzc-ZQdAhSPuMxTlO-MC_oqaOqYCrdNQ39PVxisaiE clientId: 26862190133482 clientIdAliasUsed: false clientName: My CIBA Client deliveryMode: POLL idTokenDuration: 0 refreshTokenDuration: 0 serviceAttributes: - key: attribute1-key value: attribute1-value - key: attribute2-key value: attribute2-value '400': $ref: '#/components/responses/400' '401': $ref: '#/components/responses/401' '403': $ref: '#/components/responses/403' '500': $ref: '#/components/responses/500' operationId: backchannel_authentication_complete_api x-code-samples: - lang: shell label: curl source: 'curl -v -X POST https://us.authlete.com/api/21653835348762/backchannel/authentication/complete \ -H ''Content-Type: application/json'' \ -H ''Authorization: Bearer V5a40R6dWvw2gMkCOBFdZcM95q4HC0Z-T0YKD9-nR6F'' \ -d ''{ "ticket": "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q", "result": "AUTHORIZED", "subject": "john" }'' ' - lang: java label: java source: 'AuthleteConfiguration conf = ...; AuthleteApi api = AuthleteApiFactory.create(conf); BackchannelAuthenticationCompleteRequest req = new BackchannelAuthenticationCompleteRequest(); req.setTicket("NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q"); req.setResult(BackchannelAuthenticationCompleteRequest.Result.AUTHORIZED); req.setSubject("john"); api.backchannelAuthenticationComplete(req); ' - lang: python source: 'conf = ... api = AuthleteApiImpl(conf) req = BackchannelAuthenticationCompleteRequest() req.ticket = ''NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q'' req.result = BackchannelAuthenticationCompleteResult.AUTHORIZED req.subject = ''john'' api.backchannelAuthenticationComplete(req) ' tags: - CIBA components: schemas: backchannel_authentication_request: type: object required: - parameters properties: parameters: type: string description: 'Parameters of a backchannel authentication request which are the request parameters that the backchannel authentication endpoint of the OpenID provider implementation received from the client application. The value of `parameters` is the entire entity body (which is formatted in `application/x-www-form-urlencoded`) of the request from the client application. ' clientId: type: string description: 'The client ID extracted from Authorization header of the backchannel authentication request from the client application. If the backchannel authentication endpoint of the OpenID provider implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client ID in Authorization header, the value should be extracted and set to this parameter. ' clientSecret: type: string description: 'The client secret extracted from Authorization header of the backchannel authentication request from the client application. If the backchannel authentication endpoint of the OpenID provider implementation supports Basic Authentication as a means of client authentication, and the request from the client application contained its client secret in Authorization header, the value should be extracted and set to this parameter. ' clientCertificate: type: string description: 'The client certification used in the TLS connection between the client application and the backchannel authentication endpoint of the OpenID provider. ' clientCertificatePath: type: array items: type: string description: 'The client certificate path presented by the client during client authentication. Each element is a string in PEM format. ' oauthClientAttestation: type: string description: 'The value of the `OAuth-Client-Attestation` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/). ' oauthClientAttestationPop: type: string description: 'The value of the `OAuth-Client-Attestation-PoP` HTTP header, which is defined in the specification of [OAuth 2.0 Attestation-Based Client Authentication](https://datatracker.ietf.org/doc/draft-ietf-oauth-attestation-based-client-auth/). ' cimdOptions: $ref: '#/components/schemas/cimd_options' description: 'Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. ' tagged_value: type: object properties: tag: type: string description: The language tag part. value: type: string description: The value part. backchannel_authentication_issue_request: type: object required: - ticket properties: ticket: type: string description: 'The ticket issued from Authlete''s `/backchannel/authentication` API. ' backchannel_authentication_fail_request: type: object required: - ticket - reason properties: ticket: type: string description: '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: type: string enum: - ACCESS_DENIED - EXPIRED_LOGIN_HINT_TOKEN - INVALID_BINDING_MESSAGE - INVALID_TARGET - INVALID_USER_CODE - MISSING_USER_CODE - SERVER_ERROR - UNAUTHORIZED_CLIENT - UNKNOWN_USER_ID description: '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. ' errorDescription: type: string description: 'The description of the error. This corresponds to the `error_description` property in the response to the client. ' errorUri: type: string description: '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. ' 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. ' grant_management_action: type: string description: 'The grant management action of the device authorization request. The `grant_management_action` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). ' enum: - CREATE - QUERY - REPLACE - REVOKE - MERGE backchannel_authentication_complete_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: - SERVER_ERROR - NO_ACTION - NOTIFICATION 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. ' clientId: type: integer format: int64 description: 'The client ID of the client application that has made the backchannel authentication request. ' clientIdAlias: type: string description: 'The client ID alias of the client application that has made the backchannel authentication request. ' clientIdAliasUsed: type: boolean description: '`true` if the value of the client_id request parameter included in the backchannel authentication request is the client ID alias. `false` if the value is the original numeric client ID. ' clientName: type: string description: 'The name of the client application which has made the backchannel authentication request. ' deliveryMode: $ref: '#/components/schemas/delivery_mode' clientNotificationEndpoint: type: string description: 'The client notification endpoint to which a notification needs to be sent. This corresponds to the `client_notification_endpoint` metadata of the client application. ' clientNotificationToken: type: string description: 'The client notification token which needs to be embedded as a Bearer token in the Authorization header in the notification. This is the value of the `client_notification_token` request parameter included in the backchannel authentication request. ' authReqId: type: string description: 'The newly issued authentication request ID. ' accessToken: type: string description: 'The issued access token. ' refreshToken: type: string description: 'The issued refresh token. ' idToken: type: string description: 'The issued ID token. ' accessTokenDuration: type: integer format: int64 description: 'The duration of the access token in seconds. ' refreshTokenDuration: type: integer format: int64 description: 'The duration of the refresh token in seconds. ' idTokenDuration: type: integer format: int64 description: 'The duration of the ID token in seconds. ' jwtAccessToken: type: string description: 'The issued access token in JWT format. ' resources: type: array items: type: string description: 'The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service that the client application belongs to. ' clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of the client. ' grantId: type: string description: 'the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. ' clientEntityId: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' metadataDocumentLocation: type: string format: uri description: 'The location of the client''s metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. ' metadataDocumentUsed: type: boolean description: 'Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ' grant_scope: type: object properties: scope: type: string description: 'Space-delimited scopes. ' resource: type: array items: type: string description: 'List of resource indicators. ' backchannel_authentication_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 - INVALID_TICKET - OK 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. ' authReqId: type: string description: 'The newly issued authentication request ID. ' expiresIn: type: integer format: int32 description: 'The duration of the issued authentication request ID in seconds. ' interval: type: integer format: int32 description: 'The minimum amount of time in seconds that the client must wait for between polling requests to the token endpoint. ' 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. ' backchannel_authentication_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 - UNAUTHORIZED - USER_IDENTIFICATION 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. ' clientId: type: integer format: int64 description: 'The client ID of the client application that has made the backchannel authentication request. ' clientIdAlias: type: string description: 'The client ID alias of the client application that has made the backchannel authentication request. ' clientIdAliasUsed: type: boolean description: '`true` if the value of the client_id request parameter included in the backchannel authentication request is the client ID alias. `false` if the value is the original numeric client ID. ' clientName: type: string description: 'The name of the client application which has made the backchannel authentication request. ' scopes: type: array items: $ref: '#/components/schemas/scope' description: 'The scopes requested by the backchannel authentication request. ' x-mint: metadata: description: The scopes requested by the backchannel authentication request. content: ' Basically, this property holds the value of the `scope` request parameter in the backchannel authentication request. However, because unregistered scopes are dropped on Authlete side, if the `scope` request parameter contains unknown scopes, the list returned by this property becomes different from the value of the `scope` request parameter. Note that `description` property and `descriptions` property of each `scope` object in the array contained in this property is always null even if descriptions of the scopes are registered. ' claimNames: type: array items: type: string description: 'The names of the claims which were requested indirectly via some special scopes. See [5.4. Requesting Claims using Scope Values](https://openid.net/specs/openid-connect-core-1_0.html#ScopeClaims) in OpenID Connect Core 1.0 for details. ' clientNotificationToken: type: string description: 'The client notification token included in the backchannel authentication request. ' acrs: type: array items: type: string description: 'The list of ACR values requested by the backchannel authentication request. Basically, this property holds the value of the `acr_values` request parameter in the backchannel authentication request. However, because unsupported ACR values are dropped on Authlete side, if the `acr_values` request parameter contains unrecognized ACR values, the list returned by this property becomes different from the value of the `acr_values` request parameter. ' hintType: type: string description: 'The type of the hint for end-user identification which was included in the backchannel authentication request. ' hint: type: string description: 'The value of the hint for end-user identification. ' sub: type: string description: 'The value of the `sub` claim contained in the ID token hint included in the backchannel authentication request. ' bindingMessage: type: string description: 'The binding message included in the backchannel authentication request. ' userCode: type: string description: 'The binding message included in the backchannel authentication request. ' userCodeRequired: type: boolean description: 'The flag which indicates whether a user code is required. `true` when both the `backchannel_user_code_parameter` metadata of the client (= Client''s `bcUserCodeRequired` property) and the `backchannel_user_code_parameter_supported` metadata of the service (= Service''s `backchannelUserCodeParameterSupported` property) are `true`. ' requestedExpiry: type: integer format: int32 description: 'The requested expiry for the authentication request ID (`auth_req_id`). ' requestContext: type: string description: 'The request context of the backchannel authentication request. It is the value of the request_context claim in the signed authentication request and its format is JSON. request_context is a new claim added by the FAPI-CIBA profile. ' warnings: type: array items: type: string description: 'The warnings raised during processing the backchannel authentication request. ' ticket: type: string description: 'The ticket which is necessary to call Authlete''s `/auth/token/fail` API or `/auth/token/issue` API. This parameter has a value only if the value of `grant_type` request parameter is `password` and the token request is valid. ' resources: type: array items: type: string description: 'The resources specified by the `resource` request parameters or by the `resource` property in the request object. If both are given, the values in the request object should be set. See "Resource Indicators for OAuth 2.0" for details. ' authorizationDetails: $ref: '#/components/schemas/authz_details' serviceAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of this service that the client application belongs to. ' clientAttributes: type: array items: $ref: '#/components/schemas/pair' description: 'The attributes of the client. ' dynamicScopes: type: array items: $ref: '#/components/schemas/dynamic_scope' description: 'The dynamic scopes which the client application requested by the scope request parameter. ' deliveryMode: $ref: '#/components/schemas/delivery_mode' clientAuthMethod: type: string description: 'The client authentication method that was performed. ' gmAction: $ref: '#/components/schemas/grant_management_action' grantId: type: string description: 'the value of the `grant_id` request parameter of the device authorization request. The `grant_id` request parameter is defined in [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html) , which is supported by Authlete 2.3 and newer versions. ' grant: $ref: '#/components/schemas/grant' grantSubject: type: string description: 'The subject identifying the user who has given the grant identified by the `grant_id` request parameter of the device authorization request. Authlete 2.3 and newer versions support [Grant Management for OAuth 2.0](https://openid.net/specs/fapi-grant-management.html). An authorization request may contain a `grant_id` request parameter which is defined in the specification. If the value of the request parameter is valid, {@link #getGrantSubject()} will return the subject of the user who has given the grant to the client application. Authorization server implementations may use the value returned from {@link #getGrantSubject()} in order to determine the user to authenticate. The user your system will authenticate during the authorization process (or has already authenticated) may be different from the user of the grant. The first implementer''s draft of "Grant Management for OAuth 2.0" does not mention anything about the case, so the behavior in the case is left to implementations. Authlete will not perform the grant management action when the `subject` passed to Authlete does not match the user of the grant. ' clientEntityId: type: string description: 'The entity ID of the client. ' clientEntityIdUsed: type: boolean description: 'Flag which indicates whether the entity ID of the client was used when the request for the access token was made. ' metadataDocumentLocation: type: string format: uri description: 'The location of the client''s metadata document that was used to resolve client metadata. This property is set when client metadata was retrieved via the [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD) mechanism. ' metadataDocumentUsed: type: boolean description: 'Flag indicating whether a metadata document was used to resolve client metadata for this request. When `true`, the client metadata was retrieved via the CIMD mechanism rather than from the Authlete database. ' 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. ' 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. delivery_mode: type: string enum: - PING - POLL - PUSH scope: type: object properties: name: type: string description: The name of the scope. defaultEntry: type: boolean description: '`true` to mark the scope as default. Scopes marked as default are regarded as requested when an authorization request from a client application does not contain scope request parameter. ' description: type: string description: The description about the scope. descriptions: type: array description: The descriptions about this scope in multiple languages. items: $ref: '#/components/schemas/tagged_value' attributes: type: array description: The attributes of the scope. items: $ref: '#/components/schemas/pair' backchannel_authentication_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 - FORBIDDEN 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. ' pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. cimd_options: type: object description: 'Options for [OAuth Client ID Metadata Document](https://datatracker.ietf.org/doc/draft-ietf-oauth-client-id-metadata-document/) (CIMD). These options allow per-request control over CIMD behavior, taking precedence over service-level configuration when provided. ' properties: alwaysRetrieved: type: boolean description: 'Whether to always retrieve client metadata in the CIMD context regardless of the cache''s validity. Under normal circumstances, client metadata retrieved from the location referenced by the client ID is stored in the database with an expiration time calculated using HTTP caching mechanisms (see [RFC 9111 HTTP Caching](https://www.rfc-editor.org/rfc/rfc9111.html)). Until that expiration time is reached, Authlete does not attempt to retrieve the client metadata again. When this flag is set to `true`, Authlete retrieves the client metadata regardless of the cache''s validity. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdAlwaysRetrieved`). This flag is effective only when the service supports CIMD (see `Service.clientIdMetadataDocumentSupported`) and CIMD is actually used to resolve client metadata. For example, if the client ID in a request does not appear to be a valid URI, CIMD will not be used even if the service is configured to support it. In such cases, this flag has no effect. Client metadata retrieval is performed only in the initiating request of an authorization flow, and not in any subsequent requests. For example, in the authorization code flow, metadata may be retrieved during the authorization request, but not during the subsequent token request. In contrast, in the client credentials flow, metadata retrieval may occur because the token request itself is the initiating request in the flow. ' httpPermitted: type: boolean description: 'Whether to allow the `http` scheme in client IDs in the CIMD context. The specification requires the `https` scheme, but if this flag is set to `true`, Authlete also allows the `http` scheme. The main purpose of this option is to make development easier for developers who run CIMD-enabled servers and a web server publishing client metadata on their local machines without TLS. Given this purpose, it is not recommended to enable this option in production environments unless an allowlist is used (see `Service.cimdAllowlistEnabled`). If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdHttpPermitted`). ' queryPermitted: type: boolean description: 'Whether to allow a query component in client IDs in the CIMD context. Although the specification states that a client ID "SHOULD NOT include a query string component," it does technically allow it. However, query components are prone to misuse. Therefore, Authlete does not allow them by default. Setting this flag to `true` relaxes that restriction. If this flag is included in an Authlete API call and its value is `true`, it takes precedence over the corresponding service configuration (see `Service.cimdQueryPermitted`). ' grant: type: object properties: scopes: type: array items: $ref: '#/components/schemas/grant_scope' claims: type: array items: type: string description: 'The claims associated with the Grant. ' authorizationDetails: $ref: '#/components/schemas/authz_details' dynamic_scope: type: object properties: name: type: string description: The scope name. value: type: string description: The scope value. backchannel_authentication_complete_request: type: object required: - ticket - result - subject properties: ticket: type: string description: 'The ticket issued by Authlete''s `/backchannel/authentication` API. ' result: type: string enum: - TRANSACTION_FAILED - ACCESS_DENIED - AUTHORIZED description: 'The result of the end-user authentication and authorization. One of the following. Details are described in the description. ' subject: type: string description: 'The subject (= unique identifier) of the end-user. ' sub: type: string description: 'The value of the sub claim that should be used in the ID token. ' authTime: type: integer format: int64 description: 'The time at which the end-user was authenticated. Its value is the number of seconds from `1970-01-01`. ' acr: type: string description: 'The reference of the authentication context class which the end-user authentication satisfied. ' claims: type: string description: 'Additional claims which will be embedded in the ID token. ' properties: type: array items: $ref: '#/components/schemas/property' description: 'The extra properties associated with the access token. ' scopes: type: array items: type: string description: 'Scopes to replace the scopes specified in the original backchannel authentication request with. When nothing is specified for this parameter, replacement is not performed. ' idtHeaderParams: type: string description: 'JSON that represents additional JWS header parameters for ID tokens. ' errorDescription: type: string description: 'The description of the error. If this optional request parameter is given, its value is used as the value of the `error_description` property, but it is used only when the result is not `AUTHORIZED`. To comply with the specification strictly, the description must not include characters outside the set `%x20-21 / %x23-5B / %x5D-7E`. ' errorUri: type: string description: 'The URI of a document which describes the error in detail. This corresponds to the `error_uri` property in the response to the client. ' consentedClaims: type: array items: type: string description: 'the claims that the user has consented for the client application to know. ' 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. ' refreshTokenDuration: type: integer format: int64 description: 'The duration (in seconds) of the refresh 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 refresh token in. In other cases, this request parameter is ignored. ' 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. ' responses: '403': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001215 resultMessage: '[A001215] /auth/authorization, The client (ID = 26837717140341) is locked.' '401': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001202 resultMessage: '[A001202] /auth/authorization, Authorization header is missing.' '400': description: '' content: application/json: schema: $ref: '#/components/schemas/result' example: resultCode: A001201 resultMessage: '[A001201] /auth/authorization, TLS must be used.' '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. '