Xilnex Auth - API Documentation

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

1. The base address of Xilnex Auth is https://wb-api-auth-server.azurewebsites.net.
2. Client ID and Client Secret are required to use any of the grant types.
3. The default expiration time of an authorization code is 5 minutes.
4. The default expiration time of an access token (JWT type) is 1 hour.
5. 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.
6. 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:

1. {
       "access_token": "<token>",
       "expires_in": 3600,
       "token_type": "Bearer",
       "scope": "coreapi"
   }

---

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:

1. {
       "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

• 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 ...

• Recent Articles

• Xilnex Auth - API Documentation

  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 ...

• 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 ...

• Downloading Store Sample CSV Template File in Xilnex Portal

  Overview The Download Store Sample CSV Template File feature in Store Management Import and Log allows staff to download a sample template, containing all necessary fields and proper format for importing data into the system. Preparing imported files ...

• Importing Store Details in Xilnex Portal

  Overview The Import Store Details in Xilnex Portal is a function that allows users to import store data in bulk using CSV files. Users have the option to import the store details either With updating the existing records or Without updating the ...

• Centralized Secondary Screen Media

  Secondary Screen Guidelines Current Setup (Local Media) Currently, the secondary screen relies on a local folder to display media on the POS. Xilnex POS automatically creates a folder named "SecondaryMonitorMedia" on the desktop, or users can ...

• 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 ...