> ## 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. # Complete Backchannel Authentication > 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. 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} ``` ## OpenAPI ````yaml https://spec.speakeasy.com/authlete/sdk-workspace/authlete-api-explorer-with-code-samples post /api/{serviceId}/backchannel/authentication/complete 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}/backchannel/authentication/complete: post: tags: - CIBA 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. operationId: backchannel_authentication_complete_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/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' 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.ciba.complete({ serviceId: "", backchannelAuthenticationCompleteRequest: { ticket: "NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q", result: "AUTHORIZED", 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.ciba.complete_request(service_id: '', backchannel_authentication_complete_request: Models::Components::BackchannelAuthenticationCompleteRequest.new( ticket: 'NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q', result: Models::Components::BackchannelAuthenticationCompleteRequestResult::AUTHORIZED, subject: 'john' )) unless res.backchannel_authentication_complete_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.Ciba.Complete(ctx, \"\", components.BackchannelAuthenticationCompleteRequest{\n Ticket: \"NFIHGx_btVrWmtAD093D-87JxvT4DAtuijEkLVHbS4Q\",\n Result: components.BackchannelAuthenticationCompleteRequestResultAuthorized,\n Subject: \"john\",\n })\n if err != nil {\n log.Fatal(err)\n }\n if res.BackchannelAuthenticationCompleteResponse != nil {\n // handle response\n }\n}" 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) components: schemas: 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. 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. 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. delivery_mode: type: string enum: - PING - POLL - PUSH 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. pair: type: object properties: key: type: string description: The key part. value: type: string description: The value part. 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. ````