Login as Taxpayer System

This API allows taxpayer system to get access token to be used to access other protected APIs of the solution.

Full Common API list Get Document Types


eInvoicing and eReceipt solution APIs are protected (with some exceptions) and made available only to relevant taxpayer representatives, their ERP systems.

This API is used to authenticate the ERP system calling and issue access token that allows ERP system to access those protected APIs. Note that each token issued is issued for a certain time period configured as part of eInvoicing solution, example can be found in expires_in. This means that compliant ERP systems integrating with the solution should expect that some calls can start returning not authorized error codes (see more on standard error responses) that mean that most likely token 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.


As described in the Getting started overview, solution is leveraging externalized standards based identity system for managing users and also systems that are accessing solution user interfaces and also APIs.

Therefore solution leverages OAuth 2.0 client credentials flow for authenticating systems and granting them access token that allows then to call other APIs described in this SDK that requires authorization.

Signature: POST /connect/token


Header parameter Type Description Value example
Authorization String Must contain basic authorization string created using issued Client ID and Client Secret for the ERP system. The process of creating basic authorization string should follow RFC 2617 Basic <Base64 encoded value>

Login as intermediary

if you are trying to login as intermediary then you need to add an extra header parameter to your request, this header parameter that will be mapped to the taxpayer that you are trying to login on his behalf.


Note! when you login as intermediary, permissions that are granted by the taxpayer will be applied on your profile and this will control the functionalities that you'll be able to executed on behalf of the taxpayer you are representing.

Header parameter Type Description Value example
onbehalfof String Registration number. For business in Egypt must be registration number 100015840
Body parameter Type Description Value example
grant_type String Must be “client_credentials” client_credentials
scope String Optional parameter asking for a specific access scope. In case of external access to eInvoicing APIs this parameter can be omitted InvoicingAPI


Successful Response

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 and TAGs assigned to the taxpayer, so that the system can access B2B or B2C features or both 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 using this token. InvoicingAPI

Error Responses: 400 Bad Request

Output parameter Type Description Value example
error String Possible values: invalid_request, invalid_client, invalid_grant, unauthorized_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 uses in eInvoicing solution  

Additional Considerations

Each token already includes information about the taxpayer that the system is going to represent, therefore when doing API calls afterwards the taxpayer information is available also to relying party APIs.

System authentication can be rejected if invalid client ID and secret is used to authenticate or 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.

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.