Login as Intermediary System

This API is used to authenticate the ERP system associated with an intermediary that is representing a taxpayer (acting on behalf of a specific taxpayer) calling and issue access token which allows ERP system to access those protected APIs.

Login as Taxpayer System Get All Document Types

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

When trying to login as intermediary, add an extra header parameter to the request. This header parameter will be mapped to the taxpayer that the intermediary is trying to login on his behalf.

Note! When trying to login as intermediary, permissions that are granted by the taxpayer will be applied on the intermediary's profile and this will control the functionalities that they will be able to executed on behalf of the taxpayer they are representing.

Header parameter Type Description Value example Requirement
onbehalfof String This should be the Tax Identification Number (TIN) of the taxpayer the intermediary is presenting C25845632020 Mandatory
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 One(1) hour.

Note: Your system should be responsible to obtain a new access token using this endpoint before the expiry of the current valid token to continue calling the APIs.