Skip to main content
POST
/
api
/
v1
/
auth
/
login
Login
curl --request POST \
  --url https://api.example.com/api/v1/auth/login \
  --header 'Content-Type: application/json' \
  --data '
{
  "username": "<string>",
  "password": "<string>"
}
'
{
  "200": {},
  "400": {},
  "401": {},
  "token": "<string>",
  "type": "<string>",
  "username": "<string>",
  "roles": [
    "<string>"
  ]
}

​
Overview

Authenticate a user by providing valid credentials (username or email and password). Upon successful authentication, the API returns a JWT token that must be included in subsequent API requests.

​
Request Body

​
username
string
required
Username or email address of the userValidation: Must not be blankExample: [email protected]
​
password
string
required
User’s passwordValidation: Must not be blankExample: password123

​
Response

​
token
string
required
JWT access token to be used for authentication in subsequent requestsInclude this token in the Authorization header as Bearer {token}
​
type
string
required
Token type, always returns "Bearer"
​
username
string
required
Username/email of the authenticated user
​
roles
string[]
required
List of roles assigned to the user (e.g., ["ROLE_ADMIN", "ROLE_USER"])

​
Authentication Flow

1

Validate Credentials

The API validates the provided username/email and password using Spring Security’s AuthenticationManager
2

Load User Details

Upon successful authentication, the user’s details are loaded from the database
3

Generate JWT Token

A JWT token is generated with:
  • Standard claims: subject (username), issued at, expiration
  • Custom claims: tenantId (multi-tenant isolation), role (user role)
4

Return Response

The JWT token and user information are returned to the client

​
Example Request

curl -X POST https://api.invernaderos.com/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "[email protected]",
    "password": "securePass123"
  }'

​
Example Response

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbkBncmVlbmhvdXNldGVjaC5jb20iLCJ0ZW5hbnRJZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInJvbGUiOiJBRE1JTiIsImlhdCI6MTcwMDAwMDAwMCwiZXhwIjoxNzAwMDg2NDAwfQ.signature",
  "type": "Bearer",
  "username": "[email protected]",
  "roles": ["ROLE_ADMIN"]
}

​
Status Codes

​
200
OK
Successfully authenticated. JWT token returned in response body.
​
401
Unauthorized
Invalid credentials. The username/email or password is incorrect.Common causes:
  • Incorrect password
  • User does not exist
  • Account is inactive
​
400
Bad Request
Validation error. Required fields are missing or empty.Common causes:
  • Missing username or password field
  • Empty string values

​
Using the JWT Token

After successful login, include the JWT token in all authenticated requests: 
curl -X GET https://api.invernaderos.com/api/v1/greenhouse \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
JWT Token Claims

The JWT token contains the following custom claims:

​
Security Notes

  • JWT tokens are stateless and cannot be revoked before expiration
  • Store tokens securely (e.g., HTTP-only cookies, secure storage)
  • Never expose tokens in URLs or logs
  • Use HTTPS in production to prevent token interception

​
Source Code References

  • Controller: AuthController.kt:16-25 - Login endpoint definition
  • Service: AuthService.kt:19-40 - Authentication logic
  • DTO: AuthDTOs.kt:10-17 - LoginRequest structure
  • Response: AuthDTOs.kt:56-62 - JwtResponse structure

Build docs developers (and LLMs) love

Get started for freeTalk to us