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 secures its API with JSON Web Tokens (JWT) signed using the HS256 algorithm. Every request to a protected endpoint must carry a valid token in the Authorization header. The flow is straightforward: register an account, exchange credentials for a token at the login endpoint, then attach that token to subsequent requests. This page walks through each step with complete examples.

​
How It Works

The authentication layer is implemented with python-jose and passlib (bcrypt). When you log in, the server mints a signed JWT containing your id_usuario as the sub claim and an exp claim set to the configured expiry time. On every protected request the server decodes and verifies the token — no session state is stored server-side.
1

Register an Account

Create a new FridgeRadar account by sending a JSON POST request to /api/v1/auth/register. Email addresses must be unique.Endpoint
POST /api/v1/auth/register
Content-Type: application/json
Request body
​
nombres
string
required
The user’s first name (or full name).
​
apellidos
string
The user’s surname(s). Optional — may be omitted or set to null.
​
correo
string
required
A valid email address. Must be unique across all registered accounts.
​
password
string
required
The account password. Stored as a bcrypt hash — never in plain text.
curl example
curl -X POST http://localhost:8000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "nombres": "María",
    "apellidos": "González",
    "correo": "maria@example.com",
    "password": "s3cr3tP@ss"
  }'
Response — 201 Created
​
id_usuario
integer
Auto-generated primary key for the new user account.
​
nombres
string
The first name as submitted during registration.
​
apellidos
string | null
The surname(s), or null if not provided.
​
correo
string
The confirmed email address for the account.
​
estado
string
Initial account status, typically "activo".
​
fecha_registro
string (ISO 8601 datetime) | null
Timestamp of when the account was created, in UTC.
{
  "id_usuario": 42,
  "nombres": "María",
  "apellidos": "González",
  "correo": "maria@example.com",
  "estado": "activo",
  "fecha_registro": "2024-11-15T10:32:00"
}
2

Log In and Obtain a Token

Exchange your credentials for a JWT access token. The login endpoint follows the OAuth2 Password flow, so the request body must be form-encoded — not JSON.Endpoint
POST /api/v1/auth/login
Content-Type: application/x-www-form-urlencoded
The Content-Type header must be application/x-www-form-urlencoded. Sending a JSON body will return a 422 Unprocessable Entity error.
Form fields
​
username
string
required
Your account’s email address. The OAuth2 spec names this field username even though FridgeRadar uses email addresses as identifiers.
​
password
string
required
Your account password in plain text (transmitted over HTTPS).
curl example
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d 'username=maria@example.com&password=s3cr3tP@ss'
Response — 200 OK
​
access_token
string
The signed JWT to include in all subsequent authenticated requests.
​
token_type
string
Always "bearer".
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MiIsImV4cCI6MTczMTY3MjMzM30.abc123…",
  "token_type": "bearer"
}
Store the access_token value — you will attach it to every protected request.
3

Authenticate Requests

Pass the token in the Authorization header using the Bearer scheme. The header must be present on every call to a protected endpoint.
Authorization: Bearer <access_token>
curl example — fetching the current user’s profile
curl http://localhost:8000/api/v1/usuarios/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9…"
Token expiryTokens are valid for ACCESS_TOKEN_EXPIRE_MINUTES minutes from the moment of issue. The default value is 1440 minutes (24 hours). Once a token expires you must log in again to obtain a fresh one.
Store the token in your client’s secure storage (e.g. an HTTP-only cookie or a secure credential store) rather than in localStorage to reduce XSS exposure.

​
Error Responses

StatusScenariodetail value
401 UnauthorizedToken is missing, malformed, or expired"Token inválido o expirado"
400 Bad RequestEmail or password is incorrect at loginError message from the auth service
422 Unprocessable EntityLogin request body was not form-encoded, or a required registration field is absentPydantic validation error array
A 401 response always includes the WWW-Authenticate: Bearer header, signalling to OAuth2-aware clients that a Bearer token is required. 
{
  "detail": "Token inválido o expirado"
}

​
Security Considerations

The default SECRET_KEY in config.py is "cambia-esto-en-produccion" (“change this in production”). You must override this value with a long, randomly generated secret before deploying FridgeRadar to any environment accessible from the internet. Set it via the SECRET_KEY environment variable or your .env file. A compromised secret key allows an attacker to forge valid tokens for any user.
Generate a strong secret with: 
openssl rand -hex 32
Set the result as SECRET_KEY in your deployment environment. The ALGORITHM (HS256) and ACCESS_TOKEN_EXPIRE_MINUTES (1440) values can also be overridden via environment variables if your security policy requires shorter-lived tokens.

Build docs developers (and LLMs) love

Get started for freeTalk to us