API Authentication

The API will have restricted access to authorized clients, and to ensure the security and authenticity of requests, the OAuth2 protocol with the Client Credentials flow is used.

Authentication via OAuth2 Client Credentials

Each client will receive a client_id and client_secret, which must be used to request an access token that should be sent in subsequent requests. The application will use the client_id information to query the "omni_transaction_clients" database table. This table contains specific information about the client making the request, such as:

1. client_id: Table key used to identify the client.
2. Instance: Refers to the SiTef Express instance where the client is installed. It is used to mark the resolution of pending issues directly in the SiTef Express database. Also used together with id_integrator, as this ID may "collide" between different integrators in SiTef Express instances.
3. client_type: Field used to distinguish between Client and Integrator. Currently, there are only two possible values recognized by the application (CLIENT and INTEGRATOR).
4. id_integrator: Field used to store the Integrator ID; it will be null if the user is a client.
5. se_client: Field used to store the Client ID; it will be null if the user is an integrator.

Keycloak Authentication Server

Keycloak is an open-source authentication server that implements the OAuth2 protocol and is used to generate and validate JWT tokens. As we follow the Client Credentials model, the realm used will not have registered users, only Clients, and each client will receive its credentials (client_id and client_secret). The API will have an authentication endpoint responsible for communicating with Keycloak, so the client does not need to communicate directly with Keycloak, ensuring security and simplicity in the process. First, the client must make a request to the public authentication endpoint using its credentials (client_id and client_secret) and will receive a JWT token, which must be used in all requests to private endpoints and will be validated by the API in every call using the corresponding Keycloak endpoint.

Authentication Endpoint

This endpoint allows clients to request an authentication token to access the API's private endpoints.

URL: /auth/token

HTTP Method: POST

Request Body:

{

"clientId": "string",

"clientSecret": "string"

}

Parameters:

• clientId (string): The ID of the client requesting the token. \
• clientSecret (string): The secret of the client requesting the token.

Response:

{

"accessToken": "string",

"expiresIn": "integer"

}

Response Fields:

• accessToken (string): The generated access token.
• expiresIn (integer): The time in seconds until the token expires.