Overview
MyInvois APIs are protected except the Login APIs (Login as taxpayer and Login as Intermediary System) and made available only to relevant taxpayer’s representatives and their ERP systems.
This API is used to authenticate the ERP system calling and issue access token which allows ERP system to access those protected APIs. Note that each token issued is issued for a certain time period configured as part of MyInvois System, example can be found in expires_in. This means that compliant ERP systems integrating with the solution should expect that some calls will return unauthorised error codes (see more on standard error responses) which means that most likely the token issued has expired and needs to be renewed (by another login).
Note! Authentication of the systems is done on identity service, not on the service hosting actual integration APIs. Use the Identity Service base address when creating the full URL to be called.
Signature
As described in the Getting started overview, solution is leveraging externalised standards based identity system to manage users, systems that are accessing solution user interfaces and APIs.
Therefore solution leverages OAuth 2.0 client credentials flow for authenticating systems and granting them access token that allows them to call other APIs described in this SDK which requires authorisation.
Signature:
POST /connect/token
Inputs
| Body parameter | Type | Description | Value example | Requirement |
|---|---|---|---|---|
| client_id | String | Client ID for the ERP system. | Mandatory | |
| client_secret | String | Client secret for the ERP system. | Mandatory | |
| grant_type | String | Must be ‘client_credentials’ | client_credentials | Mandatory |
| scope | String | Optional parameter asking for a specific access scope. In case of external access to e-Invoice APIs, this parameter can be omitted | InvoicingAPI | Optional |
Outputs
Successful Response
This API returns HTTP status code 200.
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| access_token | JWT token | Encoded JWT token structure that contains the fields of the issued token, token protection attributes | Encoded token value |
| token_type | String | Solution in this case returns only Bearer authentication tokens | Bearer |
| expires_in | Number | The lifetime of the access token defined in seconds | 3600 (means it is valid for one hour) |
| scope | String | Optional if matches the requested scope. Otherwise contains information on scope granted to token. This defines the APIs that client will have access to use this token. | InvoicingAPI |
Error Responses: 400 Bad Request
| Output parameter | Type | Description | Value example |
|---|---|---|---|
| error | String | Possible values: invalid_request, invalid_client, invalid_grant, unauthorised_client, unsupported_grant_type, invalid_scope | invalid_request |
| error_description | String | Optional human readable error message containing more details about error encountered. | User blocked |
| error_uri | URI | Optional URI containing more information about the error. Not used in MyInvois System |
Additional Considerations
Each token already includes information about the taxpayer that the system is going to represent, therefore taxpayer information is available to the solution APIs when API calls are being done at a later point.
System authentication can be rejected if (i) invalid client ID and secret is used to authenticate; or (ii) the system user registered against the taxpayer is blocked or expired.
Tokens issued as a result of the login operation are valid only for a pre-configured limited time. It is configured to be 1 hour.
Notes
Important !
• The system token is valid for 60 minutes. Use this token for API operations rather than generating a new one for each request. If tokens are requested for every operation, the system may impose limits on token requests. These limits will be based on each client ID and hence would be linked to the specific ERP system using the APIs.
• Always review the integration recommended practices here sdk.myinvois.hasil.gov.my/integration-practices to make sure your ERP integration is implemented following them and following healthy integration patterns.