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

The initial phase of e-Invoicing implementation in Malaysia is aimed at large enterprises with turnovers exceeding RM 100 million. These companies heavily rely on ERP systems and consistently require e-invoice generation. Consequently, the most feasible approach for them is the API-based e-invoicing model, necessitating deep integration between their business systems and the MyInvois system.

To aid in this transition, LHDN recently released the beta version of the Software Development Kit (SDK) complete with APIs and documentation, serving as a roadmap for seamless integration. The "Login as Taxpayer System" API is at the core of this integration, a critical component that streamlines authentication and access to protected APIs within the MyInvois ecosystem.

Taxpayer System Login API and Authentication

The Taxpayer System Login API is a crucial gateway for authenticating Enterprise Resource Planning (ERP) systems associated with specific taxpayers. This API plays a pivotal role in issuing access tokens, granting ERP systems the privilege to access protected APIs within the MyInvois system.

The Taxpayer System Login API is the first line of definition, ensuring the legitimacy of ERP systems accessing protected APIs. Without a robust authentication mechanism in place, the integrity and confidentiality of e-invoicing transactions would be compromised, leading to financial and reputational risks.

How does the Taxpayer Login API work?

The login API for the Taxpayer System operates based on OAuth 2.0 client credentials flow, designed to authenticate ERP systems associated with specific taxpayers and issue access tokens. 

Here's a short guide on how it works:

1. Request Authorization: To access protected APIs within the MyInvois system, an ERP system sends a request to the login API endpoint with Signature: POST/connect/token.
2. Provide Credentials: The ERP system provides its client ID and client secret as header parameters in the request. These credentials serve as the system's identity, allowing the MyInvois system to verify its authenticity.
3. Grant Type: The ERP system specifies the grant type as client_credentials in the request body. This informs the system that the request is for obtaining access based on the client's credentials.
4. Optional Scope: The business system can optionally specify a scope parameter in the request body, indicating the specific access scope it requires. For example, if the ERP system needs access to e-Invoice APIs, it can include the scope parameter with the value InvoicingAPI.
5. Token Issuance: Upon successful authentication, the login API responds with an HTTP status code 200 and issues an access token. This token is a JWT (JSON Web Token) encoded structure containing information about the token and its protection attributes.
6. Token Details: The response also includes details about the token, such as its type (Bearer token), its expiration time (expires_in), and the scope it grants access to. For example, the token may be valid for one hour (expires_in: 3600) and grant access to the specified InvoicingAPI scope.
7. Error Handling: If there are any issues with the request, such as invalid credentials or unsupported grant types, the API responds with an appropriate error code (e.g., 400 Bad Request) along with details about the error encountered.
8. Additional Considerations: It's essential to note that each token issued includes information about the taxpayer associated with the ERP system. Furthermore, tokens have a limited lifespan and expire after a pre-configured time, typically one hour. To continue accessing APIs, the ERP system needs to obtain a new access token before the current one expires.

Login as a Taxpayer API Parameters and Responses

Here are the API parameters for defining the data needed for requested actions or data retrieval and responses provide clients with the outcome of the API call.

Inputs

This is the data or information that a ERP systems sends to the MyInvois system when making a request. Inputs are categorized into two main parts: 

Header Parameter: It contains metadata about the request or the client making the request.

Body Parameter: This contains the actual payload or content of the request.

Outputs

Successful Response: This describes the response received from MyInvois system upon successful completion of the API request.

Error Responses: Provides the possible error responses and their descriptions in case of a bad request.

Integration Approach

The integration strategy between ERP systems and the Login as Taxpayer System API adheres to contemporary principles, including:

• Externalized Identity: User and system identities accessing the solution's APIs and UI are stored separately from the actual document processing modules, promoting enhanced security and scalability.
• Standards-Based Interfaces: API is constructed as REST-based interfaces, functioning with JSON as both input and output data structures. 
• Data Protection: All interactions with the Login API occur exclusively over TLS-encrypted channels, with maximum data security,

Conclusion

The Taxpayer System login API ensures secure authentication for ERP systems accessing MyInvois system to automate the e-invoice generation process. It issues access tokens for authorized systems, enhancing security and promoting compliance. With error handling capabilities and considerations for token validity, it facilitates a seamless authentication process, contributing to data integrity and trust in digital invoicing.

ClearTax is Malaysia's premier e-invoicing solution provider, offering seamless integration of any ERP or business system with the MyInvois platform. Contact our e-invoicing consultants for smooth integration and e-invoicing compliance assurance.

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