Xilnex Auth Integration Guide
Introduction
Xilnex Auth implements OAuth 2.0, a widely adopted authorization framework that enables secure access to protected resources by issuing access tokens to client applications. This document provides a comprehensive guide on how to use Xilnex Auth.
Terminology
| Term | Description |
|---|---|
| Client | Application |
| Public Client | Application involves user interaction |
| Private Client | Application without user interaction such as API |
| User / Resource Owner | End user |
| Resources | Data related to user or business |
| Resource Server | Service where data is stored |
| Auth Server | Service that authenticates and authorizes the client to access data |
| Grant Types | Ways to get tokens from Auth Server |
| Authorization Code | A temporary code received by the client after the user successfully authenticates and authorizes the app, used to obtain an access token |
| ID Token | Token that contains user identity information |
| Access Token | Token that allows a client to access protected resources |
| Refresh Token | Token used to obtain a new access token if the current access token expires |
| JWT | A type of token encoded in JSON format with claims, represented as a compact string consisting of a header, payload, and signature |
| Reference Token | A type of token that is non-readable and typically a randomly generated string, where the contents are not accessible or interpretable without validation by the authorization server |
| Client ID | A unique identifier issued to a client application by the authorization server |
| Client Secret | A secret value associated with the client ID, used to authenticate the client application during token requests |
| Scope | A set of permissions defined by the client, indicating the level of access the client has for accessing the protected resources |
| Redirect URI | The URL to which the user is redirected after authentication and authorization, where the authorization code or access token is sent (in the context of PKCE) |
Auth Server Specifications
- The base address of Xilnex Auth is https://wb-api-auth-server.azurewebsites.net.
- Client ID and Client Secret are required to use any of the grant types.
- The default expiration time of an authorization code is 5 minutes.
- The default expiration time of an access token (JWT type) is 1 hour.
- The default expiration time of a refresh token (JWT type) is 30 days; however, it will be revoked upon user logout or password change, if applicable.
- For reference tokens, both the access token and refresh token will be revoked upon user logout or password change, if applicable.
Grant Types
OAuth 2.0 defines several grant types, which are different ways a client can obtain an access token.
Notes: Xilnex Auth currently only supports client credentials and JWT.
Client Credentials
The Client Credentials Grant type allows a client application to obtain an access token by using its own credentials, without involving a user. It is used in server-to-server communication.
Request
Endpoint: POST /connect/token| Name | Data Type | Required | Description |
|---|---|---|---|
| Content-Type | String | Yes | Set it to "application/x-www-form-urlencoded" |
Request Body (application/x-www-form-urlencoded):
| Name | Data Type | Required | Description |
|---|---|---|---|
| grant_type | String | Yes | Must be set to "client_credentials" to indicate the use of the Client Credentials grant type |
| client_id | String | Yes | The unique identifier of the client application that makes the request |
| client_secret | String | Yes | The secret value of the client application that makes the request |
Example:
curl --location 'https://localhost:5000/connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=yourclientid' \
--data-urlencode 'client_secret=yourclientsecret'
Response
If everything goes well, a
200 OK response will be returned, along with the following JSON data in the response body.Response Body:
| Name | Data Type | Required | Description |
|---|---|---|---|
| access_token | String | Yes | The access token issued by the authorization server |
| expires_in | Integer | Yes | The number of seconds until the access token expires |
| token_type | String | Yes | The type of token issued specifies how the access token may be used. Always "Bearer" |
| scope | String | Yes | A space-separated list of scopes which have been granted with this token |
Example:
{
"access_token": "<token>",
"expires_in": 3600,
"token_type": "Bearer",
"scope": "coreapi"
}
Access Token
To use the access token, include it in the following header in API calls:
| Name | Data Type | Required | Description |
|---|---|---|---|
| Authorization | String | Yes | Valid access token following the format "Bearer <Access Token>" |
Example:
curl --location 'https://localhost:7001/data' \
--header 'Authorization: Bearer <token>'
Related Articles
Integrating with Xilnex: Event Triggers & Webhook Configuration
Overview Xilnex Event Hub is an integration framework that enables your system to automatically dispatch real-time notifications to external applications whenever a defined business action occurs — such as completing a sale, creating a client, or ...Available Events: Xilnex Event Hub
Last Updated: 05 May 2026 Sales # Event Name 1 Create Sales 2 Confirm Sales 3 Confirm Sales v2 4 Complete Sales 5 Complete Sales v2 6 Cancel Sales 7 Update Sales 8 Cancel Sales Order 9 Confirm Sales Order 10 Complete Sales Order 11 Post Quotation to ...Managing OAuth Client Credentials
Overview Xilnex Auth implements the OAuth 2.0 protocol to govern service-to-service authorization. Client credentials serve as the authentication identity for backend services, enabling them to authorize, or be authorized by, other services within ...OAuth Project & Client Permission Management
Overview The OAuth Project & Client Permission module controls which roles can access, configure, and manage OAuth projects and client credentials within the system. Permissions are managed under System Configuration > User Roles Permission > All ...
Recent Articles
Available Events: Xilnex Event Hub
Last Updated: 05 May 2026 Sales # Event Name 1 Create Sales 2 Confirm Sales 3 Confirm Sales v2 4 Complete Sales 5 Complete Sales v2 6 Cancel Sales 7 Update Sales 8 Cancel Sales Order 9 Confirm Sales Order 10 Complete Sales Order 11 Post Quotation to ...Integrating with Xilnex: Event Triggers & Webhook Configuration
Overview Xilnex Event Hub is an integration framework that enables your system to automatically dispatch real-time notifications to external applications whenever a defined business action occurs — such as completing a sale, creating a client, or ...LiveOrder New UI Announcement
LiveOrder — New Ordering Experience Now Available What's New? We're excited to introduce LiveOrder New UI, a redesigned ordering experience built to make ordering faster and easier for your customers. What's Changing — and Why It Matters We've ...How to Cancel an E-Invoice on Dashboard
Overview Sometimes cancelling an e-invoice is inevitable. Common situations include: Incorrect buyer information (e.g., wrong name, TIN, or address) Transaction was voided or order was cancelled after invoice issuance Duplicate e-invoice issued for ...Guidelines to Set Up Promotion for Walk-in (System Default)
Guidelines to Set Up Promotion for Walk-in (System Default) Previously, the system did not have a specific indicator for walk-in customers. As a result, all promotion rules applied equally to all customer types, including walk-in customers. However, ...
Popular Articles
Basic - How to create a voucher-coupon
Voucher and coupon definition Voucher can be generated in bulk and can be used once Coupon can only be created one at a time (reusable code) and can be use multiple times Pre-voucher / coupon setup There are 2 things need to be prepared before we can ...Understanding DuitNow QR Payment in ClassicPOS
Introduction This document introduces the DuitNow QR payment feature available in the Xilnex Retail POS, enabling merchants to accept payments conveniently through Malaysia's national QR payment standard. The integration of DuitNowQR simplifies the ...Basic - How to change custom cost to another branch that don’t have custom cost
Change custom cost to another branch that don’t have custom cost 1. Get the item list from the location with custom cost (Item Code, Name, Custom Cost) 2. Make sure the Show Location Price are selected 3. Export the item list in Excel 4. The file ...Intermediate - How to Bill & Post to Sales from Transfer Note
1.0 Purpose A bill is required from transfer note when an inventory transfer involves financial transactions, cost allocation, or compliance with tax and accounting regulations. It is used when stock is moved between outlets that operate as separate ...Basic - How to enable E-Receipt Portal and QR Code Setup on Printing format in Xilnex
Enable E-Receipt Portal Enable the E-receipt functionality Once Enabled, you will be getting the E-Receipt portal link Continue under Theme & Styling, enabled for the E-Invoice (LHDN) You can customize the look and feel of the E-Receipt portal ...