Login as Intermediary System

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.