Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/LizandroCanul/back_sdo/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

JSON Web Tokens (JWT) are the primary authentication mechanism for the Yucatan Public Works API. After successful login, you’ll receive a JWT token that must be included in all subsequent API requests.

​
Obtaining a Token

To obtain a JWT token, send a POST request to the /auth/login endpoint with your credentials.

​
Endpoint

POST /auth/login

​
Request Body

​
email
string
required
User’s email address
​
password
string
required
User’s password

​
Example Request

curl -X POST http://localhost:3000/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "password": "admin123"
  }'

​
Success Response

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI3YzNhNjg5MS0xMjM0LTU2NzgtOWFiYy1kZWYwMTIzNDU2NzgiLCJlbWFpbCI6ImFkbWluQHl1Y2F0YW4uZ29iLm14Iiwicm9sZXMiOiJhZG1pbiIsImlhdCI6MTYxNjIzOTAyMn0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  "user": {
    "id": "7c3a6891-1234-5678-9abc-def012345678",
    "email": "[email protected]",
    "roles": "admin",
    "mustChangePassword": false
  }
}

​
Error Response

If the credentials are invalid, you’ll receive a 401 Unauthorized response: 
{
  "statusCode": 401,
  "message": "Credenciales inválidas",
  "error": "Unauthorized"
}

​
Token Structure

JWT tokens consist of three parts separated by dots (.): 
header.payload.signature

​
Token Payload

The token payload contains the following claims:
​
sub
string
Subject - The user’s unique ID (UUID)
​
email
string
The user’s email address
​
roles
string
The user’s role (e.g., “admin” or “user”)
​
iat
number
Issued At - Timestamp when the token was created

​
Example Decoded Payload

{
  "sub": "7c3a6891-1234-5678-9abc-def012345678",
  "email": "[email protected]",
  "roles": "admin",
  "iat": 1616239022
}
The token payload is generated in auth.service.ts:27-31 using the user’s information.

​
Using Tokens in API Requests

Once you have a token, include it in the Authorization header of your requests using the Bearer scheme.

​
Authorization Header Format

Authorization: Bearer <your_access_token>

​
Example Requests

curl -X GET http://localhost:3000/obras \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

​
Token Validation

The API validates tokens using the Passport JWT strategy. The validation process:
  1. Extracts the token from the Authorization header
  2. Verifies the signature using the secret key
  3. Checks expiration - expired tokens are rejected
  4. Decodes the payload and attaches user info to the request
jwt.strategy.ts:15-18
async validate(payload: any) {
  return { userId: payload.sub, email: payload.email, roles: payload.roles };
}
If the token is missing, invalid, or expired, the API will return a 401 Unauthorized response.

​
Token Expiration

The current implementation sets token expiration based on the JWT configuration. When a token expires:
  • The API will reject the token with a 401 Unauthorized response
  • The client must request a new token by logging in again
jwt.strategy.ts:10
ignoreExpiration: false, // Tokens must not be expired
Currently, the API does not implement token refresh functionality. Users must log in again to obtain a new token after expiration.

​
Security Best Practices

  • Never store tokens in localStorage (vulnerable to XSS attacks)
  • Use httpOnly cookies or secure session storage
  • Consider using memory storage for highly sensitive applications
  • Implement automatic re-authentication when tokens expire
  • Show user-friendly messages for expired sessions
  • Consider implementing token refresh for better UX
  • Never expose tokens in URLs or logs
  • Use HTTPS in production to prevent token interception
  • Implement token revocation for compromised accounts

Authentication Overview

Learn about the authentication system

Roles & Permissions

Understand role-based access control

Build docs developers (and LLMs) love

Get started for freeTalk to us