RECENTLY PUBLISHED

Login as Intermediary System API: Authentication and Access for Intermediaries

Updated on: Apr 22nd, 2024

17 min read

The initial phase of e-Invoicing implementation in Malaysia targets large enterprises with turnovers exceeding RM 100 million. These companies heavily rely on ERP systems and third-party intermediaries or middleware for real-time and consistent e-invoice generation.

Consequently, their most practical approach is the API-based e-invoicing model, which requires deep integration between their business and MyInvois systems.

To facilitate this transition, LHDN recently launched Software Development Kit (SDK) Version 1.0 complete with APIs and documentation, providing a roadmap for seamless integration.

The "Login as Intermediary System" API plays a vital role in authenticating and accessing protected APIs within the MyInvois ecosystem.

Intermediary System Login API and Authentication

As the concept of e-invoicing is new, most businesses are likely to depend on a third-party intermediary or middleware specialized in e-invoicing solutions for smooth integration with the MyInvois system.

The Intermediary System Login API is utilized to verify the middleware operating on behalf of the taxpayer. This intermediary can be a third-party service provider or a software system managing e-invoicing for multiple taxpayers.

The main purpose of this API is to authenticate the enterprise source system, granting it access to certain protected APIs within the MyInvois ecosystem.

Access Token Issuance

Upon successful authentication, the API issues a specialized access token to the ERP system. This token enables the intermediary to interact with protected APIs on behalf of the specific taxpayer it represents.

Authorization

The access token provided by this API facilitates access to resources based on the intermediary's authorization to act on behalf of the taxpayer. It ensures that the intermediary can access the necessary resources securely.

Expiration and Renewal

Each access token issued by this API has an expiration time of 1 hour configured within the MyInvois System. When the token expires, the ERP system may encounter unauthorized errors while accessing the APIs. To resolve this, the ERP system must renew the token by logging in again.

Note: Authentication of systems occurs through the Identity Service, not the service hosting the actual integration APIs. It's essential to use the base address of the Identity Service when creating the full URL for API calls.

How does the Intermediary Login API work?

The Intermediary Login API is the gateway for intermediary systems to authenticate themselves within the MyInvois system, enabling them to act on behalf of specific taxpayers. This API facilitates the issuance of access tokens necessary for intermediary systems to access protected APIs within the ecosystem.

Authentication Process:

Intermediary systems authenticate themselves and obtain access tokens to act on behalf of taxpayers using the Intermediary Login API

Request Initiation: To initiate the authentication process, the intermediary system sends a POST request to the designated endpoint, typically /connect/token, utilizing OAuth 2.0 client credentials flow.
Header Parameter: Along with the request, the intermediary system includes an extra header parameter named onbehalfof, specifying the Tax Identification Number (TIN) of the taxpayer it represents. This parameter establishes the context for the authentication process, linking the intermediary system to the respective taxpayer.

Parameter	Type	Description
client_id	String	The Client ID specific to the ERP system.
client_secret	String	The Client Secret associated with the ERP system.
grant_type	String	Must be set to "client_credentials" to indicate the type of grant being requested.
scope (Optional)	String	Specifies the access scope requested by the ERP system. If omitted, it defaults to a predefined scope.

Body Parameter: The body parameter contains essential authentication details required for accessing the e-invoicing API, such as client credentials and grant type.

Parameter	Type	Description
client_id	String	The Client ID specific to the ERP system.
client_secret	String	The Client Secret associated with the ERP system.
grant_type	String	Must be set to "client_credentials" to indicate the type of grant being requested.
scope (Optional)	String	Specifies the access scope requested by the ERP system. If omitted, it defaults to a predefined scope.

Response Handling

The Intermediary Login API responds with encoded JWT tokens upon successful authentication, granting access to e-invoicing APIs.

Successful Response (HTTP 200): Upon successful authentication, the API returns an HTTP status code of 200 along with the following information:

Parameter	Type	Description
access_token	JWT token	An encoded JWT token containing relevant information such as token protection attributes.
token_type	String	Indicates the type of authentication token. In this case, it will be "Bearer".
expires_in	Number	Specifies the lifetime of the access token in seconds.
scope	String	(Optional) Indicates the granted scope, defining the APIs accessible using the token.

Error Handling (HTTP 400): In case of errors, such as invalid requests or unauthorized access, the API responds with an HTTP status code of 400. Additionally, it provides detailed error information including:

Parameter	Type	Description
error	String	Specifies the type of error encountered.
error_description	String	(Optional) Provides a human-readable error message for further context.
error_uri	URI	(Optional) Offers a URI containing additional information about the error.

Additional Considerations

The issued access token inherently includes information about the taxpayer being represented, simplifying subsequent API calls by providing contextual information.
Authentication may fail if invalid client credentials are provided or if the system user associated with the taxpayer is blocked or expired.
Tokens issued have a limited validity period, typically one hour. It is the responsibility of the system to renew the access token before expiration to ensure uninterrupted API access.

Conclusion

By following the prescribed authentication process, intermediary systems can securely access the designated APIs within the MyInvois ecosystem, facilitating seamless interactions on behalf of taxpayers.

Also Read
Login as Taxpayer System API: Authentication and Access for Taxpayer and Intermediary

Index