JWT Tokens

Learn how to obtain and use JWT tokens for API authentication

What are JWT Tokens?

JSON Web Tokens (JWT) are a secure way to transmit information between parties as a JSON object. In StockAPI, JWT tokens are used to authenticate users and maintain secure sessions.

A JWT token contains encoded information about the user, including:

• User ID
• Username
• User role
• Token expiration time

Token Structure

When you successfully log in, StockAPI generates a JWT token with the following payload:

// From authController.js:23-27
const token = jwt.sign(
    { id: user._id, username: user.username, role: user.role },
    process.env.JWT_SECRET,
    { expiresIn: '4h' }
);

The token includes:

• id - The user’s unique database ID
• username - The user’s username
• role - The user’s role (e.g., “vendedor”, “developer”)
• Expiration set to 4 hours from generation

Obtaining a Token

To obtain a JWT token, you need to authenticate using the /login endpoint.

Login Request

cURL

curl -X POST https://api.stockapi.com/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin2",
    "password": "1234"
  }'

Successful Response

If authentication is successful, you’ll receive a response like this:

{
  "message": "Login exitoso",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6IjY3MzRhYmNkZWYxMjM0NTY3ODkwIiwidXNlcm5hbWUiOiJhZG1pbjIiLCJyb2xlIjoidmVuZGVkb3IiLCJpYXQiOjE3MzE1MDAwMDAsImV4cCI6MTczMTUxNDQwMH0.abc123def456ghi789jkl012mno345pqr678stu901vwx234yz",
  "user": {
    "username": "admin2",
    "role": "vendedor"
  }
}

Error Responses

Usuario no encontrado (401)

{
  "message": "Usuario no encontrado"
}

The username provided does not exist in the database.

Contraseña incorrecta (401)

{
  "message": "Contraseña incorrecta"
}

The password provided is incorrect.

Error en el login (500)

{
  "message": "Error en el login",
  "error": "Error message details"
}

A server error occurred during authentication.

Using Tokens in Requests

Once you have a token, you must include it in the Authorization header of all requests to protected endpoints.

Authorization Header Format

The token must be sent in the following format:

Authorization: Bearer <your-token-here>

Note the space between “Bearer” and the token. The middleware splits the header value on the space character to extract the token.

Example Authenticated Requests

Create Product

curl -X POST https://api.stockapi.com/api/products \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coca Cola 2L",
    "price": 250,
    "stock": 50,
    "category": "Bebidas"
  }'

Token Verification Process

When you send a request with a token, the verifyToken middleware validates it:

// From jwtMiddleware.js:8-25
function verifyToken(req, res, next) {
    // El token normalmente se manda en headers: Authorization: Bearer <token>
    const authHeader = req.headers['authorization'];

    if (!authHeader) return res.status(401).json({ message: 'No se proporcionó token' });

    const token = authHeader.split(' ')[1]; // 'Bearer <token>'

    if (!token) return res.status(401).json({ message: 'Token inválido' });

    try {
        const decoded = jwt.verify(token, process.env.JWT_SECRET);
        req.user = decoded; // guardamos info del usuario en la request
        next(); // seguimos al controlador
    } catch (err) {
        res.status(403).json({ message: 'Token expirado o inválido' });
    }
}

The middleware:

1. Checks if the Authorization header is present
2. Extracts the token from the “Bearer” format
3. Verifies the token signature and expiration
4. Decodes the token and attaches user information to the request
5. Allows the request to proceed or returns an error

Token Expiration

Tokens expire 4 hours after generation. After expiration, you must log in again to obtain a new token.

Handling Expired Tokens

When a token expires, requests will fail with a 403 status:

{
  "message": "Token expirado o inválido"
}

When you receive this error:

1. Make a new login request with valid credentials
2. Obtain a new token
3. Update your application’s stored token
4. Retry the original request

Best Practices

Store Securely

Store tokens securely in your application (e.g., httpOnly cookies, secure storage)

Handle Expiration

Implement automatic token refresh logic before the 4-hour expiration

Don't Share Tokens

Never share tokens between users or expose them in client-side code

Clear on Logout

Remove stored tokens when users log out of your application

Common Authentication Errors

Status Code	Message	Cause	Solution
401	No se proporcionó token	Missing Authorization header	Include the Authorization header in your request
401	Token inválido	Malformed token or missing Bearer prefix	Check the Authorization header format
403	Token expirado o inválido	Token has expired or signature is invalid	Log in again to obtain a new token
401	Usuario no encontrado	Invalid username during login	Verify the username is correct
401	Contraseña incorrecta	Invalid password during login	Verify the password is correct

Next Steps

User Roles

Learn about role-based access control

Products API

Start making authenticated requests to manage products