Login
For you to receive your JWT and be able to use our APIs for your business, you need to log in and validate your login for security reasons.
Login
Endpoint
Fields
| Field | Type | Description |
|---|---|---|
email | string | The email you provided when creating an account through the create account endpoint. |
password | string | The password you provided when creating an account through the create account endpoint. |
You must formalize your JSON in this way to hit our API:
Request body
{
"email": "your.email@provider.com",
"password": "UseAStrongPassword123!"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/login" \
-H "Content-Type: application/json" \
-d '{
"email": "your.email@provider.com",
"password": "UseAStrongPassword123!"
}'
Now, in your email, you will receive an authorization token to validate the login.
Validate Login
After you receive the email token, you complete the login at the validate-login endpoint. What you send here depends on whether the access has 2FA (TOTP) enabled:
- Without 2FA — send
email+emailTokenand you immediately receive your tokens. - With 2FA enabled — after the email token is accepted you must also provide the
otpfrom your authenticator app (see When 2FA (TOTP) is enabled below).
Endpoint
Fields
| Field | Type | Required | Description |
|---|---|---|---|
email | string | Yes | The same email used to log in. |
emailToken | string | Yes | The token sent to your email. |
otp | string | Conditional | The one-time code from your authenticator app. Required only if the access has 2FA (TOTP) enabled. |
Your JSON should look like this:
Request body
{
"email": "your.email@provider.com",
"emailToken": "874484"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/validate-login" \
-H "Content-Type: application/json" \
-d '{
"email": "your.email@provider.com",
"emailToken": "874484"
}'
If the access does not have 2FA enabled, you immediately receive your accessToken and refreshToken — you're done.
When 2FA (TOTP) is enabled
If the access has 2FA enabled, the request above (without otp) does not return tokens. Instead, once the email token is validated, the response is:
{
"mfaRequired": true
}
That is your cue to read the current code from your authenticator app and call the same endpoint again, this time including the otp field:
Request body (with OTP)
{
"email": "your.email@provider.com",
"emailToken": "874484",
"otp": "123456"
}
Request example (with OTP)
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/validate-login" \
-H "Content-Type: application/json" \
-d '{
"email": "your.email@provider.com",
"emailToken": "874484",
"otp": "123456"
}'
Once the otp is valid, you receive your accessToken and refreshToken.
If you already know the access has 2FA enabled, you can skip the extra round trip and send email, emailToken, and otp together on the first call.
- The
otpmust be exactly 6 digits; anything else, or a wrong code, returns HTTP 400 with{ "error": "InvalidFieldError: otp is invalid" }. Retry with the current code from your authenticator app. - The email token is valid for 10 minutes and is single-use: it is consumed once you receive your tokens, so every new session starts again from the Login step above. Getting
{ "mfaRequired": true }does not consume it. - To enable the authenticator, see the MFA Guide in the Security section.
Both codes are capped per email over a 1-hour window, and the cap answers with HTTP 429:
emailToken: every validate-login call counts. After 5 calls without a correct token, further calls returntoo many invalid code attempts, please try again lateruntil the hour passes, even with the correct token.otp: the 5th wrong code returnstoo many invalid authenticator codes, please try again laterinstead of the 400. The email token is invalidated, and requesting a new one through Login does not reset the counter: until the hour passes, validate-login keeps answering 429, with or withoutotp. Then start again from the Login step.
A successful validation resets the counter for that code.
After validation, you should now receive your accessToken and your refreshToken.
Remember not to share these tokens with anyone.
Refresh Token
A refresh token is used to obtain a new access token without requiring the user to log in again. It helps maintain user authentication securely and improves the user experience by reducing the need for frequent logins. Refresh tokens typically have a longer lifespan than access tokens and are stored securely to prevent unauthorized access.
Endpoint
Field
| Field | Type | Description |
|---|---|---|
refreshToken | string | The refreshToken you received at the validate login endpoint (or from this endpoint itself, if you refresh repeatedly). |
Remember not to share these tokens with anyone.
Your JSON needs to look like this:
Request body
{
"refreshToken": "eyJhbdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
Request example
curl -X POST "https://api.sandbox.avenia.io:10952/v2/auth/refresh" \
-H "Content-Type: application/json" \
-d '{
"refreshToken": "eyJhbdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}'
And you will receive a new batch of accessToken and refreshToken again, allowing you to keep rotating your accessToken:
Response
{
"accessToken": "eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"refreshToken": "eyJhbdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
}
Conclusion
Now you have the power to interact with our APIs, having your JWT in hand and a way to continuously refresh its validity, allowing you to use our services for a long time without needing to log in again.
Remember not to share your accessToken or refreshToken Token with anyone.