Authentication Flow

Frontend Client

Each request must contain the following headers:

X-Tenant-ID: The Tenant ID provided by the Consiglio Verde admin.
Referer: The URL of the frontend client.

The Login API (/auth/login/) will return the following response:

{
    "otp_method": "EMAIL",
    "request_id": "3690d97c-667a-4579-9b8d-9cdeade8d35a|B5276fc199bb40C2524363c76d74ff0a",
    "email": "ma***********si@consiglioverde.com"
}

Where:

otp_method: The method used to send the OTP. The possible values are EMAIL and TOTP
request_id: The request ID to be used in the Login Confirm API.

In the Login Confirm API (/auth/login/confirm/), the request must have the following body:

{
    "otp": "123456",
    "request_id": "3690d97c-667a-4579-9b8d-9cdeade8d35a|B5276fc199bb40C2524363c76d74ff0a"
}

Where:

otp: The OTP sent to the user.
request_id: The request ID received in the Login API.

The response will contain the following data:

{
    "expiry": "2024-01-01T23:59:00.000000Z",
    "token": "56e0b15f2076fda900286d39865b1a7657498e33e0e2c11bd0b269f8da180c95",
    "user": {
        "info": {
            "id": "faf79bc0-bb47-4f87-a50e-32e8369a0fab",
            "email": "ma***********si@consiglioverde.com",
            "username": "mario.rossi",
            "is_active": true
        },
        "otp": {
            "method": "EMAIL",
            "initialized": false
        }
    }
}

Where the token is the JWT token to be used in in headers like this:

{
    "Authorization" : "Token 56e0b15f2076fda900286d39865b1a7657498e33e0e2c11bd0b269f8da180c95"
}

Backend Client

During the configuration phase, the client generates a cryptographic key pair, consisting of a public key and a private key. The public key is provided to the system during the configuration phase to enable the digital signatures of requests sent by the client to be verified.

In each request made, the client includes the following fields in the headers:

X-Tenant-ID: The Tenant ID (UUID) provided by the Consiglio Verde admin.
X-Timestamp: The timestamp of the request in the epoch format.
X-Signature: A digital signature generated using the algorithm ECDSA (Elliptic Curve Digital Signature Algorithm), in particular secp256k1 class of curves. This signature is calculated by combining the body of the request, the timestamp, the HTTP method and the endpoint of the request, using the client's private key. The concatenation format is {method}|{path}|{timestamp}|{body}. The signature is sent as a hexadecimal string, and will be verified by the system using the public key previously provided, thus ensuring the authenticity and integrity of the request.

Authentication Flow

Frontend Client

1. Login

2. Login Confirm

Backend Client