Development Guidelines

Sequence Diagram

Step 1 Create an application to get client ID and client secret

Step 2 Initiate authentication request with Paotang application and authorize your mobile application

curl --location --request POST '{{baseUrl_paotangAuth}}/oauth2/app2app/auth' \
--header 'Content-Type: application/json' \ 
--data-raw '{
  "client_id": "{client_id}",
  "redirect_uri": "yourapp://{redirect_url}",
  "response_type": "code",
  "scope": [
      "offline", 
      "openid",
    ],
  "state": "randomstate"
}'

{
  "deeplinkUrl": "{the_deeplink}"
}

{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid, unknown, or malformed. The OAuth 2.0 Client is not allowed to request scope.",
  "state": "thisisstate"
}

let urlString: String = unwrapped(deeplinkUrl, with: "")
guard let url = URL(string: urlString) else { return }
UIApplication.shared.open(url)

private fun openBrowserByUrl(deeplinkUrl: String) {
        val intent = Intent(Intent.ACTION_VIEW,Uri.parse(deeplinkUrl))
        startActivity(intent)
}

Step 3 Receive an authorization code or error response that will redirect user to your mobile application

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleTypeRole</key>
    <string>Editor</string>
    <key>CFBundleURLName</key>
    <string>$(BUNDLE_ID)</string>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>appschemename</string>
    </array>
  </dict>
</array>

// Example url : appschemename://
// AndroidManifest.xml
<intent-filter android:autoVerify="true">
  <action android:name="android.intent.action.VIEW" />
  <category android:name="android.intent.category.DEFAULT" />
  <category android:name="android.intent.category.BROWSABLE" />
  <data android:scheme="appschemename" />
</intent-filter>

partnerapp://{redirect_url}?code=wDXuLe3HqtS5cEiUd8mgdyGdW03qeVAyofcwF2sdtwg.4bePd6mVmmfOAacp
-iasRWJNGujhI7dR4yhE-IllW8E&scope=openid+offline&state=thisisstate

scheme://yourapp/{redirect_url}?error=access_denied&error_description=The+resource+owner+denied+the+request.&state=thisisstate

Step 4 Exchange the token to obtain an access token

To obtain an access token, ensure that the state parameters received alongside the authorization code from Paotang application matches the one you specify during user authentication and the authorization request.

Request

Parameter	Type	Required	Description
code	string	Required	A code obtained from redirect URL.
grant_type	string	Required	The way an application obtains an access token. You need to specify ‘authorization_code’ for using app-to-app flow.
redirect_uri	string	Required	The redirect URI used during initiate authentication request
client_id	string	Required	The client ID obtained from creating an application
client_secret	string	Required	The client secret obtained from creating an application
state	string	Required	The state used during initiate authentication request
scope	string	Required	The scopes requested from the user

Example request:

curl --location --request POST '{{baseUrl_paotangAuth}}/oauth2/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'code={your authorization code that obtains an access token}' \
--data-urlencode 'grant_type=authorization_code' \
--data-urlencode 'redirect_uri={your redirect url}' \
--data-urlencode 'client_id={your client id}' \
--data-urlencode 'client_secret={your client secret}' \
--data-urlencode 'state={your unique alphanumeric string}' 

ⓘ
{{baseUrl_paotangAuth}} for public environment is https://paotang-pass.devops.krungthai.com


ⓘ
{{baseUrl_paotangAuth}} for sandbox environment is https://paotang-pass-sandbox.devops.krungthai.com

Response

Property	Type	Description
access_token	string	Access token, which remains valid for 1 hour.
expires_in	number	The amount of time in seconds until the access token expires.
id_token	string	JSON Web Token (JWT) that includes information about the user. This field is returned only if OpenID is specified in the scope.
refresh_token	string	A token is used to obtain a new access token, which remains valid until 24 hours after the access token is issued.
scope	string	Permissions granted by the user
token_type	string	Bearer

Example response:

{
  "access_token": "_-xO_oggXQwIThjjo8iPm5J2lf8Tsz33zdCGgd-bzBg.h31h1COKfEq4xdJbnuu9en_UQwXTJkV7Gf9aghuL9uY",
  "expires_in": 3599,
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6InB1YmxpYzpj...",
  "refresh_token": "8EqQaJ3Xp8VX7tfG71m0L2SBEaXRwcXtFYwc34qB4qM.hnSvfnq0xypwIfXciAXgGHp7LcNOlbyddcs-cYVm2L4",
  "scope": "offline openid",
  "token_type": "Bearer"
}

About an ID token

An ID token is a JSON Web Token (JWT) that contains claims about the authentication of an end-user by an authorization server. It is designed to be consumed by the client application (also known as the relying party) and contains essential information about the user and the authentication event.

Structure of an ID Token

An ID token typically has 3 parts, separated by dots (.):

1. Header: This part contains metadata about the token, including the type of token (JWT) and the signing algorithm used.

Example:

{
  "alg": "RS256",
  "typ": "JWT"
}

2. Payload: This part contains the claims, which are statements about an entity. The payload includes standard claims like iss (issuer), sub (subject), aud (audience), exp (expiration time), and other optional claims.

Example:

{
  "at_hash": "6wMYdxWc64oZvXpn29UggQ",
  "aud": [
    "6c366ffe-eec5-4921-a71e-441d4d8444e4"
  ],
  "auth_time": 1682010030,
  "acr": "PIN_FACECMP",
  "exp": 1682013728,
  "iat": 1682010128,
  "iss": "https://paotang-id.devops.krungthai.com/",
  "jti": "69974269-621e-4f72-b00b-be8fa330794b",
  "rat": 1682010029,
  "sid": "e94530bb-211e-48f3-88a8-cd4566848dc2",
  "sub": "nvPDZgNvyK5xj61KIoctIqUTXfRzSAA27AKXD7rXGGBgYxEwCwXxI4M9eVcuiehMPUJH9KFJW5TKChP6F0DVpsMr"
}

3. Signature: This part verifies that the token was issued by a trusted source and that it has not been tampered with. It is created by signing the header and payload with the authorization server’s private key.

How an ID token is used

Upon receiving the ID token, the client application must validate it by following these steps:

1. Verifying the signature: Ensuring the token’s signature is valid and that it was issued by the trusted OP.

2. Checking the claims: Verifying that the token is not expired (exp claim) and that the token is intended for the client (aud claim).

3. Validating the authentication method: If your application requires a specific authentication method for the user's intended action, verify that the acr claim in the id_token matches your requirement. Reject the session and re-initiate authentication with the required acr if it does not match.

After verifying the token, the sub claim can serves as a unique key (anonymous ID) to identify the user across multiple sessions and interactions with the RP. It allows the RP to recognize the same user across different login sessions.

Validate the authentication method (acr claim)

When you specify the acr parameter during initialization (Step 2), Paotang will challenge the user with the corresponding authentication method. However, the acr request parameter is sent from your client and is not, on its own, proof of the method the user performed. The signed id_token returned in this step contains an acr claim that reflects the method Paotang actually used to authenticate the user. Because the id_token is signed by Paotang, this claim cannot be tampered with in transit and is the source of truth for authorization decisions in your backend.

For any flow that requires a specific authentication method (for example, a high-value transaction that must be confirmed with face comparison), your backend must:

1. Verify the id_token signature against Paotang's published JWKS.
2. Validate the standard claims (iss, aud, exp, iat).
3. Compare the acr claim against the authentication method required by the action the user is attempting. If it does not match, reject the request and re-initiate authentication with the correct acr.
4. Optionally, check auth_time against your freshness policy if the action requires recent authentication (step-up).

acr claim values

Value	Meaning
PIN	The user authenticated with PIN only.
PIN_FACECMP	The user authenticated with PIN and passed facial comparison.

Example validation (pseudocode)

// After exchanging the authorization code for tokens (Step 4)
const claims = verifyJwt(idToken, paotangJwks); // signature + iss/aud/exp/iat

const requiredAcr = "PIN_FACECMP"; // determined by the action the user is attempting

if (claims.acr !== requiredAcr) {
  // Do NOT proceed. Re-initiate authentication with acr=PIN_FACECMP.
  return rejectAndReauthenticate(requiredAcr);
}

// Safe to proceed with the protected action

⚠
Common pitfall
Do not store the acr value you sent in the Step 2 request and use it as the authentication method for downstream authorization checks. That value is what your application asked for, not what the user actually performed. Always read acr from the verified id_token claims.

Step 5 Get customer profile information from access token

curl --location --request POST '{{baseUrl}}/v1/paotangpass/get-customer-profile' \
--header 'Authorization: Bearer {your access token}'

{
  "code": "0000",
  "message": "",
  "data": {
    "cid": "1234567890123",
    "title": "นาย",
    "fullNameTh": {
      "thaiFirstName": "วายุ",
      "thaiMiddleName": "ชื่อกลางถ้ามี",
      "thaiLastName": "มีตัง"
    },
    "fullNameEn": {
      "engFirstName": "Vayu",
      "engMiddleName": "Optional",
      "engLastName": "Meetang"
    },
    "gender": "M",
    "birthDate": "25400122",
    "mobileNo": "0123456789",
    "email": "test@example.com",
    "workProfile": {
      "occupationCode": "1257",
      "occupationValue": "กลุ่มเทคโนโลยี",
      "occupationGroup": "07",
      "occupationGroupValue": "พนักงานบริษัท/ลูกจ้างเอกชน",
      "subOccupationGroup": "99",
      "subOccupationGroupValue": "อื่นๆ",
      "salary": "6",
      "salaryValue": "40,001-60,000 บาท"
    },
    "legalAddress": {
      "address": "123",
      "subDistrict": "แขวงจอมพล",
      "subDistrictCode": "0400",
      "district": "เขตจตุจักร",
      "districtCode": "1030",
      "stateProv": "กรุงเทพมหานคร",
      "stateProvCode": "10",
      "postalCode": "10900",
      "country": "TH",
      "phoneNo": "012345678"
    },
    "mailingAddress": {
      "address": "123",
      "subDistrict": "แขวงจอมพล",
      "subDistrictCode": "0400",
      "district": "เขตจตุจักร",
      "districtCode": "1030",
      "stateProv": "กรุงเทพมหานคร",
      "stateProvCode": "10",
      "postalCode": "10900",
      "country": "TH",
      "phoneNo": "012345678"
    },
    "officeAddress": {
      "officeName": "ABC",
      "address": "123",
      "subDistrict": "แขวงจอมพล",
      "subDistrictCode": "0400",
      "district": "เขตจตุจักร",
      "districtCode": "1030",
      "stateProv": "กรุงเทพมหานคร",
      "stateProvCode": "10",
      "postalCode": "10900",
      "country": "TH",
      "phoneNo": "012345678",
      "phoneExt": "01"
    }
  }
}