Romsoft Gestión Clínica API: JWT Authentication Guide

The Romsoft Gestión Clínica API protects its resources with JSON Web Token (JWT) bearer authentication. A custom TokenValidationHandler — a DelegatingHandler registered early in the ASP.NET Web API message pipeline — intercepts every inbound HTTP request, extracts the Authorization header, and cryptographically validates the token before the request ever reaches a controller. This means authentication is enforced uniformly across the entire API surface without any per-controller configuration.

How Authentication Works

When a request arrives at the server, TokenValidationHandler runs before any controller action:

It attempts to read the Authorization header and extract a Bearer token.
If no token is present, it forwards the request down the pipeline unchanged — the controller’s own [Authorize] attribute will then produce a 401 Unauthorized response.
If a token is present, it validates the token’s signature, issuer, audience, and expiry using parameters read from appSettings.
On success, it sets Thread.CurrentPrincipal and HttpContext.Current.User to the claims identity from the token, allowing controllers to identify the calling user.
On failure (invalid signature, expired token, malformed JWT), it short-circuits the pipeline and returns 401 Unauthorized immediately. An unexpected server error returns 500 Internal Server Error.

Only POST /api/Account/Login is exempt from this requirement. It is decorated with [AllowAnonymous] and will accept requests that carry no token at all. Every other endpoint requires a valid Bearer token.

Obtaining a Token

Call POST /api/Account/Login with a JSON body containing your credentials. The endpoint accepts a LoginDTO object with the following fields:

Username

string

required

The username of the account as stored in the SEG_USUARIO table.

Password

string

required

The plaintext password for the account. The business-logic layer handles any hashing or comparison internally.

ValidacionAD

boolean

Optional flag for Active Directory validation. Pass false or omit this field for standard database-backed authentication.

curl -X POST https://<your-server>/api/Account/Login \
  -H "Content-Type: application/json" \
  -d '{
    "Username": "admin",
    "Password": "yourpassword"
  }'

On success, the Data field of the response envelope contains a SEG_USUARIOLoginDTO object. The token field within that object is the JWT you will use for all subsequent requests.

{
  "Success": true,
  "Warning": false,
  "Message": null,
  "Data": {
    "id_usuario": 1,
    "id_rol": 2,
    "usuario": "admin",
    "clave": "***",
    "apellidos": "Pullima",
    "nombres": "Administrador",
    "estado": "A",
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6ImFkbWluIiwibmJmIjoxNjkwMDAwMDAwLCJleHAiOjE2OTAwMjg4MDAsImlhdCI6MTY5MDAwMDAwMH0.SIGNATURE"
  }
}

Data.id_usuario

integer

The unique numeric identifier of the authenticated user.

Data.id_rol

integer

The role identifier assigned to the user, used for authorization decisions within the application.

Data.usuario

string

The username string — matches the Username field sent in the login request.

Data.clave

string

The stored password or hash value for the account, as returned from the database mapping.

Data.apellidos

string

The user’s surname(s), as stored in the system.

Data.nombres

string

The user’s given name(s).

Data.estado

string

Account status. "A" means active.

Data.token

string

The signed JWT bearer token. Copy this value and include it in the Authorization header of every subsequent request.

If the username or password is incorrect, the server returns an HTTP 200 status with Warning: true in the envelope. No 401 is issued at the HTTP level for bad credentials:

{
  "Success": true,
  "Warning": true,
  "Message": "El usuario no existe o los datos son incorrectos.",
  "Data": null
}

Always check both Success and Warning in the response envelope. A 200 OK HTTP status does not guarantee a successful login — you must verify that Warning is false and Data.token is non-null before proceeding.

Using the Token

Once you have a token, include it in every request as an HTTP Authorization header using the Bearer scheme:

Authorization: Bearer <your-token-here>

curl -X POST https://<your-server>/api/CVN_PLAN_SEGURO/GetAllActives \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -d '{}'

The TokenValidationHandler performs a prefix check: if the header value starts with "Bearer ", it strips those seven characters and validates the remainder as a raw JWT string. You may also send the raw token without the Bearer prefix, though the standard Bearer prefix is strongly recommended for interoperability.

Token Validation Details

The server reads all JWT configuration from Web.config <appSettings>. The following keys must be correctly configured on the server for token validation to work:

appSetting Key	Purpose	Example Value
`JWT_SECRET_KEY`	HMAC-SHA256 signing secret used to verify the token signature.	`4b436579-7850-45bc-be7a-0e8a7c7715c9`
`JWT_AUDIENCE_TOKEN`	Expected `aud` claim — must match the value used when the token was generated.	`http://localhost:44390`
`JWT_ISSUER_TOKEN`	Expected `iss` claim — must match the value used when the token was generated.	`http://localhost:44390`
`JWT_EXPIRE_MINUTES`	Token lifetime in minutes from issuance. Default is `28800` (20 days).	`28800`

The validator enforces:

Signature — the token must be signed with the JWT_SECRET_KEY using HMAC-SHA256.
Issuer — the iss claim must equal JWT_ISSUER_TOKEN.
Audience — the aud claim must equal JWT_AUDIENCE_TOKEN.
Lifetime — DateTime.UtcNow must be before the token’s exp claim. Expired tokens are rejected outright.

Token Expiry

Tokens expire 20 days after issuance by default (JWT_EXPIRE_MINUTES = 28800, which is 28,800 minutes). After expiry, any request carrying the expired token will receive a 401 Unauthorized response. To continue working, log in again to obtain a fresh token.

There is no token refresh endpoint. When a token expires, you must call POST /api/Account/Login again with full credentials.

Error Responses

Scenario	HTTP Status	Description
No `Authorization` header present	`401 Unauthorized`	Token was not found in the request headers.
Token present but invalid (bad signature, wrong issuer/audience)	`401 Unauthorized`	`SecurityTokenValidationException` was thrown during validation.
Token present but expired	`401 Unauthorized`	The `LifetimeValidator` determined `DateTime.UtcNow >= exp`.
Unexpected server error during validation	`500 Internal Server Error`	An unhandled exception occurred inside `TokenValidationHandler`.

Summary

Call POST /api/Account/Login

Send your Username and Password in a JSON body. No Authorization header is needed.

Check the response envelope

Confirm Success: true and Warning: false. Extract Data.token.

Attach the token to all subsequent requests

Add Authorization: Bearer <token> to every HTTP request header.

Re-authenticate when the token expires

Tokens are valid for 20 days. Call /api/Account/Login again to get a new token after expiry.

For the complete login endpoint schema, see the Login API reference.

Get Started

Architecture

Configuration

Romsoft Gestión Clínica API: JWT Authentication Guide

How Authentication Works

Obtaining a Token

Using the Token

Token Validation Details

Token Expiry

Error Responses

Summary

Build docs developers (and LLMs) love

Get Started

Architecture

Configuration

Documentation Index

​How Authentication Works

​Obtaining a Token

​Login Response

​Failed Login

​Using the Token

​Token Validation Details

​Token Expiry

​Error Responses

​Summary

Build docs developers (and LLMs) love

How Authentication Works

Obtaining a Token

Login Response

Failed Login

Using the Token

Token Validation Details

Token Expiry

Error Responses

Summary