Overview
The VIGIA API uses JWT (JSON Web Token) based authentication with role-based access control (RBAC) and multi-tenancy support. All authenticated endpoints require a valid bearer token in the Authorization header.Authentication Flow
- Login: Send credentials to
/api/v1/auth/loginto receive a JWT token - Token Storage: Store the token securely on the client side
- API Requests: Include the token in the Authorization header for all protected endpoints
- Token Refresh: Tokens expire after 480 minutes (8 hours) by default
Multi-Tenant Architecture
VIGIA supports multi-tenant authentication using theX-Tenant header. Each tenant has isolated data and users.
If no
X-Tenant header is provided, the system falls back to the legacy tenant mode.Tenant Header
Token Structure
JWT tokens issued by VIGIA contain the following claims:| Claim | Type | Description |
|---|---|---|
sub | string | User ID (string representation) |
uid | integer | User ID (numeric) |
username | string | Username |
email | string | User email address |
role | string | Primary role (e.g., “admin”, “qf”) |
roles | array | All assigned roles |
tenant | string | Tenant identifier |
trace | string | Request trace ID for logging |
exp | integer | Expiration timestamp |
Available Roles
VIGIA uses a predefined set of roles for access control:- admin: Full system access, administrative privileges
- qf: Qualified Person (Farmacovigilancia)
- responsable_fv: Pharmacovigilance Manager
- qa: Quality Assurance
- direccion_tecnica: Technical Director
- legal: Legal Department
- soporte: Support/Help Desk
Users must have at least one role assigned to authenticate successfully. The system automatically selects “admin” as the primary role if present, otherwise uses the first role in the list.
Security Headers
Required Headers for All Authenticated Requests
Optional Headers
Token Expiration
Tokens expire after 480 minutes (8 hours) by default. When a token expires, clients receive a401 Unauthorized response and must re-authenticate.
Password Requirements
- Minimum length: 6 characters
- Stored using bcrypt hashing algorithm
- Password changes require current password verification
Error Responses
All authentication endpoints return standard error responses:401 Unauthorized
- Invalid credentials provided
- Token is invalid or malformed
- User not found
403 Forbidden
- User account is inactive
- User has no roles assigned
422 Unprocessable Entity
- Required fields are missing
- Password is too short (< 6 characters)
Rate Limiting
Best Practices
- Store tokens securely: Use httpOnly cookies or secure storage mechanisms
- Never expose tokens: Don’t log tokens or include them in URLs
- Use HTTPS: Always use encrypted connections in production
- Implement token refresh: Refresh tokens before expiration for seamless UX
- Handle 401 responses: Redirect to login when tokens expire
- Validate tenant context: Always include the correct X-Tenant header
Next Steps
Login Endpoint
Learn how to authenticate and obtain JWT tokens
Permissions
Understand role-based access control