Skip to main content

​
Overview

Session management endpoints allow frontend applications to check authentication state and retrieve user session information. These endpoints are exposed by the sgivu-gateway BFF (Backend-for-Frontend).

​
Base URL

https://your-domain.com

​
Get Session Status

GET /auth/session
Retrieves the current authenticated user’s session information including claims from the JWT token. Authentication: Required - Must be authenticated via OAuth2 Authorization: None (any authenticated user)

​
Response

​
sub
string
Subject identifier (username)
​
name
string
Full name of the authenticated user
​
email
string
Email address of the authenticated user
​
roles
array
Array of role names assigned to the user
​
permissions
array
Array of permission strings (e.g., user:read, vehicle:create)
​
rolesAndPermissions
array
Combined array of roles and permissions for authorization checks
​
iat
integer
Token issued at timestamp (Unix epoch)
​
exp
integer
Token expiration timestamp (Unix epoch)
{
  "sub": "steven",
  "name": "Steven Rodriguez",
  "email": "[email protected]",
  "roles": ["ADMIN"],
  "permissions": [
    "user:read",
    "user:create",
    "user:update",
    "user:delete",
    "vehicle:read",
    "vehicle:create",
    "vehicle:update",
    "vehicle:delete"
  ],
  "rolesAndPermissions": [
    "ROLE_ADMIN",
    "user:read",
    "user:create",
    "user:update",
    "user:delete",
    "vehicle:read",
    "vehicle:create",
    "vehicle:update",
    "vehicle:delete"
  ],
  "iat": 1709740800,
  "exp": 1709744400
}

​
Status Codes

  • 200 OK - Session information retrieved successfully
  • 401 Unauthorized - Not authenticated or token expired

​
Example

curl -X GET https://your-domain.com/auth/session \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Validate Credentials

POST /api/validate-credentials
Validates user credentials in real-time during the login process. Provides immediate feedback without submitting the complete login form. Authentication: None (used during login flow) Content-Type: application/json

​
Request Body

​
username
string
required
Username to validate
​
password
string
required
Password to validate
{
  "username": "jperez",
  "password": "SecureP@ss123"
}

​
Response

​
valid
boolean
Indicates whether the credentials are valid
​
reason
string
If valid is false, provides the reason for validation failure. Possible values:
  • invalid_credentials - Username or password is incorrect
  • disabled - User account is disabled
  • locked - User account is locked
  • expired - User account has expired
  • credentials - Credentials have expired
  • service_unavailable - User service is unreachable
null if valid is true

​
Success Response

{
  "valid": true,
  "reason": null
}

​
Failure Response

{
  "valid": false,
  "reason": "invalid_credentials"
}

​
Status Codes

  • 200 OK - Validation completed (check valid field for result)
  • 400 Bad Request - Malformed request or missing required fields
  • 500 Internal Server Error - Server error during validation

​
Example

curl -X POST https://your-domain.com/api/validate-credentials \
  -H "Content-Type: application/json" \
  -d '{
    "username": "jperez",
    "password": "SecureP@ss123"
  }'

​
Logout

GET /logout
Invalidates the current user session and clears authentication cookies. Authentication: Optional (works with or without authentication)

​
Response

Redirects to the login page or application home page. 
HTTP/1.1 302 Found
Location: /login

​
Example

curl -X GET https://your-domain.com/logout \
  -H "Cookie: SESSION=..."

​
Session Storage

SGIVU uses Spring Session with JDBC for session persistence:
  • Sessions are stored in PostgreSQL (SPRING_SESSION tables)
  • Sessions survive application restarts
  • Supports distributed deployments with session sharing

​
Session Configuration

  • Session timeout: Configurable via Spring Session settings
  • Cookie name: SESSION
  • Cookie attributes: HttpOnly, Secure (in production), SameSite=Lax

​
Security Notes

​
Internal Service Authentication

The credentials validation endpoint uses the X-Internal-Service-Key header for communication between sgivu-auth and sgivu-user:
Never expose the internal service key publicly. This key should only be used for service-to-service communication.

​
JWT Claims

The session endpoint exposes claims from the JWT token including:
  • Standard claims: sub, iat, exp, iss, aud
  • Custom claims: rolesAndPermissions - used for authorization

​
Authorization Headers

The gateway propagates user information to downstream services via headers:
  • X-User-ID: User ID from the token
  • X-Username: Username from the token
  • Authorization: Bearer token for resource server validation

​
Error Responses

​
401 Unauthorized

{
  "error": "unauthorized",
  "message": "Full authentication is required to access this resource"
}

​
500 Internal Server Error

{
  "error": "internal_error",
  "message": "An unexpected error occurred during validation"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us