Getting Started
OAuth 2.0 Integration Guide

OAuth 2.0 Integration Guide

Overview

Integrate OAuth 2.0 to securely access services through third-party servers.

Configuration

POST {BaseURL}/api/v1/configure/configure-redirect-url
Content-Type: application/json
Authorization: Basic base64encode({clientId:clientSecret})
{
  "white_list_redirect_urls": [
    "http://domain_webhook"
]
}
 

Step 1: Generate Connect Link

Construct the URL to initiate the OAuth flow:

{BaseURL}/connect?client_id={client_id}&redirect_url={encoded_redirect_url}&state={state}

Parameters

ParameterDescriptionRequired
BaseURLThe base URL of the APIYes
client_idThe client's unique identifierYes
encoded_redirect_urlURL to redirect after authentication. Must be URL encodedYes
stateA unique state to maintain state between redirectsNo

Example URL Encoding

Suppose your redirect URL is:

https://example.com/callback?param1=value1&param2=value2

After URL encoding, it becomes:

https%3A%2F%2Fexample.com%2Fcallback%3Fparam1%3Dvalue1%26param2%3Dvalue2

Complete Example

Using the encoded redirect URL in the OAuth flow URL:

https://api.example.com/connect?client_id=your_client_id&redirect_url=https%3A%2F%2Fexample.com%2Fcallback%3Fparam1%3Dvalue1%26param2%3Dvalue2&state=your_unique_state

Note

Ensure that the redirect_url is URL-encoded to handle special characters properly. This allows the API to correctly parse the redirect URL.

Step 2: Redirect Handling

Upon successful authentication, users are redirected with an authToken:

redirect_url?authToken={authToken}

Step 3: Token Request

Exchange the authToken for access and refresh tokens:

POST {BaseURL}/api/v1/auth/authorize/connect
Content-Type: application/json
Authorization: Basic base64encode({clientId:clientSecret})
{
  "auth_token": "{authToken}"
}

Headers

  • Content-Type: application/json
  • Authorization: Basic base64encode({clientId:clientSecret})
    • The clientId:clientSecret should be base64 encoded.

Request Parameters

ParameterDescriptionRequired
auth_tokenTemporary token from Step 2Yes

Successful Response

{
  "access_token": "your_access_token_here",
  "refresh_token": "your_refresh_token_here",
  "business_info": {
    "moc_id": "1234567890",
    "company_name_en": "CH168 Co., Ltd",
    "company_name_kh": "ក្រុមហ៊ុនស៊ីអេច១៦៨",
    "tin": "1234567890",
    ...
  }
}

Response Parameters

FieldDescription
access_tokenToken to access the API securely
refresh_tokenToken to renew the access_token
business_infoObject containing business details

Business Information Parameters

FieldDescription
endpoint_idThe main identifier of this entity (CamInvoice ID). (e.g. KHUID00001234).
moc_idMinistry of Commerce ID, a unique identifier for the company
company_name_enThe official name of the company in English
company_name_khThe official name of the company in Khmer
tinTax Identification Number, unique tax number for the company
date_of_incorporationThe date on which the company was officially registered
business_typeType of business the company is involved in
cityThe city where the company is located
countryThe country code for Cambodia (KH)
phone_numberThe primary contact number for the company
emailThe email address for business correspondence

Step 4: Make API Calls

To make API calls, replace ACCESS-TOKEN with your access token in the authorization header: -H Authorization: Bearer ACCESS-TOKEN. When your access token expires, request a new one by calling /api/v1/token with your refresh token.

💡
This guide assumes that you have already set up your client_id and know your redirect URL.