Skip to main content

​
POST /api/v1/auth/login

Authenticate a user and receive a JWT token for accessing protected endpoints.

​
Request

​
username
string
required
Registered username
  • Min length: 4 characters
  • Max length: 50 characters
​
password
string
required
User password
  • Min length: 6 characters
  • Max length: 100 characters

​
Response

​
message
string
Success message
​
userId
UUID
Unique identifier for the authenticated user
​
username
string
Authenticated username
​
token
string
JWT token valid for 24 hours

​
Code Examples

curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "surgeon_master",
    "password": "justina2024"
  }'

​
Response Example

200 OK
{
  "message": "Login exitoso",
  "userId": "550e8400-e29b-41d4-a716-446655440000",
  "username": "surgeon_master",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJKdXN0aW5hX0JhY2tlbmQiLCJzdWIiOiJzdXJnZW9uX21hc3RlciIsInVzZXJJZCI6IjU1MGU4NDAwLWUyOWItNDFkNC1hNzE2LTQ0NjY1NTQ0MDAwMCIsInJvbGUiOiJST0xFX1NVUkdFT04iLCJpYXQiOjE3MDk2Njc2MDAsImV4cCI6MTcwOTc1Mzk5OX0.signature"
}
400 Bad Request
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "El username debe tener entre 4 y 50 caracteres",
  "path": "/api/v1/auth/login"
}
401 Unauthorized
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Credenciales incorrectas",
  "path": "/api/v1/auth/login"
}
The login endpoint also sets an HttpOnly cookie named jwt-token with the JWT value. Web browsers will automatically include this cookie in subsequent requests.

​
POST /api/v1/auth/register

Register a new surgeon account in the system.

​
Request

​
username
string
required
Desired username
  • Min length: 4 characters
  • Max length: 50 characters
  • Must be unique
​
password
string
required
User password
  • Min length: 6 characters
  • Max length: 100 characters
  • Will be hashed with BCrypt

​
Response

​
message
string
Success or error message
​
error
string
Error description (only present on failure)

​
Code Examples

curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "new_surgeon",
    "password": "secure_password123"
  }'

​
Response Examples

200 OK
{
  "message": "Usuario registrado con éxito"
}
400 Bad Request - Existing User
{
  "error": "El usuario ya existe"
}
400 Bad Request - Validation Error
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 400,
  "error": "Bad Request",
  "message": "La contraseña debe tener entre 6 y 100 caracteres",
  "path": "/api/v1/auth/register"
}
New users are automatically assigned the ROLE_SURGEON role. AI system accounts must be created manually with ROLE_AI.

​
GET /api/v1/auth/me

Retrieve information about the currently authenticated user.

​
Authentication

This endpoint requires a valid JWT token in the Authorization header or jwt-token cookie.

​
Request

No request body required. Include JWT token: 
Authorization: Bearer <your-jwt-token>

​
Response

​
id
UUID
User’s unique identifier
​
username
string
User’s username
​
role
string
User’s role (ROLE_SURGEON or ROLE_AI)

​
Code Examples

curl -X GET http://localhost:8080/api/v1/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Response Examples

200 OK
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "username": "surgeon_master",
  "role": "ROLE_SURGEON"
}
401 Unauthorized
{
  "timestamp": "2024-03-05T10:30:00",
  "status": 401,
  "error": "Unauthorized",
  "message": "Full authentication is required to access this resource",
  "path": "/api/v1/auth/me"
}

​
Default Credentials

The application initializes with default accounts for testing:
UsernamePasswordRole
surgeon_masterjustina2024ROLE_SURGEON
ia_justinaia_secret_2024ROLE_AI
Security Notice: Change these default passwords immediately in production environments. Never use default credentials in deployed systems.

​
Error Handling

All authentication endpoints return consistent error responses with:
  • timestamp - ISO 8601 formatted error time
  • status - HTTP status code
  • error - HTTP status reason phrase
  • message - Human-readable error description
  • path - Request path that caused the error

​
Common Validation Errors

  • Username too short/long
  • Password too short/long
  • Missing required fields
  • Username already exists (registration)
  • Invalid credentials (login)

​
Next Steps

JWT Authentication

Learn about JWT token structure and security

Surgery Endpoints

Access surgical trajectory and analysis data

Build docs developers (and LLMs) love

Get started for freeTalk to us