Product Overview

Methods for retrieving authenticated user information.
Using the UserInfo API, clients can obtain verified user attributes based on the scopes requested during the authentication process. The service supports both the Authorization Code Flow and the CIBA backchannel authentication flow.

API Overview

Base URL

• Test service Base URL: https://test-api.tbcbank.ge
• Production service Base URL: https://api.tbcbank.ge

Product Endpoints

• UserInfo: /userinfo

Returns the authenticated user’s profile information as a signed JWT. Requires a valid access token issued via Authorization Code Flow or CIBA.

Authentication Flows Overview

Authorization Code Flow

The Authorization Code Flow is an OAuth 2.0 and OpenID Connect standard mechanism for obtaining an access token through a browser-based user authentication.

Flow steps

1. The client redirects the user to the Authorization Endpoint to authenticate.
2. After successful login, the Authorization Server redirects back to the client with an authorization code.
3. The client exchanges this code at /oauth/token using grant_type=authorization_code.
4. The server issues an access token (and optionally a refresh token).
5. The client calls /userinfo with header Authorization: Bearer {access_token}.
6. The UserInfo API returns a signed JWT containing claims such as sub, name, email, depending on requested scopes.

Use cases
• Web applications
• Mobile applications using redirect-based authentication
• Any scenario where user interaction through browser is allowed

CIBA – Client Initiated Backchannel Authentication

CIBA (Backchannel Authentication) allows clients to authenticate users without a browser redirect, typically through a mobile banking app or another trusted device.

Flow steps

1. Backchannel Authentication Request
   The client initiates authentication by calling the bc-authorization endpoint. The request includes the client identifier, requested scopes, optional claims, and login_hint with information about the user. The authorization server creates an authentication request and returns auth_req_id. At this stage, the user receives a push notification or message in their banking application asking them to confirm or deny the request.
2. Polling the Token Endpoint
   After receiving auth_req_id, the client repeatedly calls the token endpoint using grant_type urn:openid:params:grant-type:ciba. If the user has not yet approved the request, the token endpoint returns authorization_pending. The client continues polling until the user approves the request or the request expires.
3. User Enters User Code or Confirms on Device
   The user confirms the authentication request on their mobile device. In the case of the user_code scenario, the user manually enters the provided code, and the client submits this code along with id_token_hint by calling bc-authorization again. This step completes the user verification process and allows the authorization server to finalize the authentication.
4. Successful Token Retrieval
   After the user has approved the request, the client retries the token endpoint using the same auth_req_id. The authorization server returns an access token. This token can now be used for calling protected endpoints.
5. Retrieving User Information
   The client calls the userinfo endpoint with Authorization: Bearer {access_token}. The server returns a signed JWT containing the user’s requested claims, such as given_name, family_name, personal_id_number, birthdate, email, or msisdn, depending on the scope and claims defined in step 1.

Use cases
• Banking mobile apps
• Strong Customer Authentication (SCA)
• Transactions requiring out-of-band confirmation
• Scenarios where redirection or browser interaction is not possible

UserInfo Endpoint Description

Endpoint:

• /userinfo

Method:

• GET

Authorization:

• Authorization: Bearer {access_token} (required)

Response

• Content-Type: application/jwt
• Signed JWT containing user claims based on scopes requested in authorization
• If the token is expired or invalid → 401 Unauthorized