Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/EstefanoARG/FridgeRadar/llms.txt

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

FridgeRadar uses JSON Web Tokens (JWT) for stateless authentication. Every protected endpoint requires an Authorization: Bearer <token> header. The typical flow is straightforward: create an account with the registration endpoint, exchange your credentials for a token via the login endpoint, then attach that token to all future requests. Tokens are signed with HS256 using a server-side secret and expire after a configurable window (default 24 hours).

​
Registration and login flow

1

Register a new user account

Send a POST request to /api/v1/auth/register with a JSON body. The nombres field and correo (email) are required; apellidos is optional.
curl -X POST https://your-fridgeradar-host/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "nombres": "María",
    "apellidos": "García",
    "correo": "maria@example.com",
    "password": "s3cur3P@ss!"
  }'
A successful registration returns 201 Created with a UsuarioResponse body:
{
  "id_usuario": 42,
  "nombres": "María",
  "apellidos": "García",
  "correo": "maria@example.com",
  "fecha_registro": "2024-07-01T10:00:00",
  "estado": "activo"
}
FieldTypeDescription
id_usuariointAuto-assigned primary key
nombresstringFirst name(s)
apellidosstring | nullLast name(s)
correostringUnique email address
fecha_registrodatetime | nullAccount creation timestamp
estadostringAccount status (e.g. "activo")
2

Log in and obtain an access token

The login endpoint uses OAuth2 password flow — credentials must be sent as application/x-www-form-urlencoded form fields, not JSON. The username field must contain the user’s email address.
curl -X POST https://your-fridgeradar-host/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "username=maria@example.com&password=s3cur3P@ss!"
A successful login returns a TokenResponse:
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer"
}
Store the access_token securely — the React frontend keeps it in localStorage under the key "token".
3

Attach the token to API requests

Pass the token in the Authorization header on every request to a protected endpoint:
curl -X GET https://your-fridgeradar-host/api/v1/inventario/hogar/1 \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
Any request made without a valid token — or with an expired one — receives a 401 Unauthorized response:
{
  "detail": "Token inválido o expirado"
}

​
Token expiry

Tokens expire after ACCESS_TOKEN_EXPIRE_MINUTES minutes from the time they are issued. The default value is 1440 minutes (24 hours). Once a token expires, the user must log in again to obtain a fresh one. You can override the default by setting ACCESS_TOKEN_EXPIRE_MINUTES in your environment or .env file.
The JWT sub claim contains the id_usuario integer, which the backend uses to identify the authenticated user on every protected route via get_current_user.

​
Frontend Axios integration

The React frontend (Vite + Axios) centralises all token-handling in frontend/src/api/client.js. A request interceptor reads the token from localStorage and injects it into every outbound request automatically: 
import axios from 'axios'

const api = axios.create({
  baseURL: '/api/v1',
  headers: { 'Content-Type': 'application/json' },
})

// Attach token from localStorage to every request
api.interceptors.request.use((config) => {
  const token = localStorage.getItem('token')
  if (token) {
    config.headers.Authorization = `Bearer ${token}`
  }
  return config
})

// Redirect to /login on 401
api.interceptors.response.use(
  (res) => res,
  (err) => {
    if (err.response?.status === 401 && window.location.pathname !== '/login') {
      localStorage.removeItem('token')
      window.location.href = '/login'
    }
    return Promise.reject(err)
  },
)

export default api
A response interceptor watches for 401 responses: if the server rejects a token (expired or invalid), the interceptor clears the stale token from localStorage and redirects the user to /login. The auth.js helper wraps the two auth endpoints, using URLSearchParams to correctly encode the OAuth2 form body for login: 
import api from './client'

export const login = (correo, password) =>
  api.post('/auth/login', new URLSearchParams({ username: correo, password }), {
    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
  })

export const register = (data) => api.post('/auth/register', data)
In production, set SECRET_KEY to a long, randomly-generated string and never commit it to source control. Anyone who obtains the secret can forge valid tokens for any user. Use an environment variable or a secrets manager to inject it at runtime.

Build docs developers (and LLMs) love

Get started for freeTalk to us