Authenticating with the Spartans Gym API

The Spartans Gym API uses stateless JSON Web Token (JWT) authentication. When a staff member logs in, the server signs a token containing their identity and role. That token must then be included in the Authorization header of every subsequent request to a protected endpoint. There are no sessions, cookies, or API keys — just the signed token.

How Bearer Authentication Works

After a successful login, include the token as a Bearer credential in every protected request:

# Use the token from login in all subsequent requests
curl https://YOUR_API/api/clients \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The authenticate middleware on each protected route extracts the token from the Authorization header, verifies the signature against JWT_SECRET, and — if valid — attaches the decoded payload to req.user so controllers can read the caller’s id, email, and role.

Token Payload

Every JWT issued by the API contains the following claims:

Claim	Type	Description
`id`	`number`	Internal database ID of the staff user
`email`	`string`	Email address used to log in
`role`	`'admin' \| 'recepcionista'`	Permission level determining resource access

Token Expiry

Tokens expire according to the JWT_EXPIRES_IN environment variable (default: 7d). After expiry the server returns 401 Unauthorized with "error": "Token inválido o expirado". The client must re-authenticate via POST /api/auth/login to obtain a fresh token.

Set JWT_EXPIRES_IN to a shorter value (e.g. 8h) in production environments to reduce the window of exposure if a token is ever leaked.

Endpoints

Authenticates a staff user by email and password, and returns a signed JWT alongside the user record (without the password hash). This is the only auth endpoint that does not require a token.

curl -X POST https://YOUR_API/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@spartansgym.com","password":"ChangeMe123!"}'

Request Body

string

required

The staff user’s registered email address.

password

string

required

The staff user’s plaintext password. Verified server-side against the stored bcrypt hash — never stored or logged.

Success Response `200`

{
  "success": true,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user": {
      "id": 1,
      "email": "admin@spartansgym.com",
      "role": "admin",
      "createdAt": "2024-01-10T08:00:00.000Z",
      "updatedAt": "2024-11-01T14:30:00.000Z"
    }
  }
}

Show Response field reference

success

boolean

required

Always true on a successful login.

data

object

required

Wrapper object containing the token and user record.

Show data fields

data.token

string

required

Signed JWT to use as a Bearer token in subsequent requests.

data.user.id

number

required

Unique database ID of the authenticated user.

data.user.email

string

required

Email address of the authenticated user.

data.user.role

string

required

Role of the authenticated user: admin or recepcionista.

data.user.createdAt

string

required

ISO 8601 timestamp of when the user account was created.

data.user.updatedAt

string

required

ISO 8601 timestamp of the last account update.

Error Responses

Status	`error` value	Cause
`400 Bad Request`	`"Email y contraseña son requeridos"`	Either `email` or `password` was omitted from the request body
`401 Unauthorized`	`"Credenciales incorrectas"`	No user found with that email, or the password does not match the stored hash

GET /api/auth/me

Returns the database record for the currently authenticated user. Useful for bootstrapping a frontend session after a page load — call this endpoint with a stored token to confirm the token is still valid and retrieve fresh user data. Requires: Authorization: Bearer <token>

curl https://YOUR_API/api/auth/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Success Response `200`

{
  "success": true,
  "data": {
    "id": 1,
    "email": "admin@spartansgym.com",
    "role": "admin",
    "createdAt": "2024-01-10T08:00:00.000Z"
  }
}

The updatedAt field is intentionally omitted from this response — only id, email, role, and createdAt are returned. The password hash is never included in any auth response.

Error Responses

Status	`error` value	Cause
`401 Unauthorized`	`"Token no proporcionado"`	`Authorization` header is missing or does not start with `Bearer`
`401 Unauthorized`	`"Token inválido o expirado"`	Token signature is invalid or the token has expired
`404 Not Found`	`"Usuario no encontrado"`	Token is valid but the user record no longer exists in the database

POST /api/auth/logout

Signals the client to discard the current session. Because the API is stateless, logout is handled entirely on the client side — the server does not maintain a denylist of revoked tokens. This endpoint simply confirms the action and returns a success message. Requires: Authorization: Bearer <token>

curl -X POST https://YOUR_API/api/auth/logout \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

Success Response `200`

{
  "success": true,
  "message": "Sesión cerrada correctamente"
}

Tokens are not invalidated server-side when logout is called. A token remains cryptographically valid until its exp claim is reached. If a token is compromised, the only way to revoke it immediately is to rotate the JWT_SECRET environment variable and restart the server — this invalidates all currently issued tokens at once.

Frontend Token Storage

The Spartans Gym frontend stores the JWT in Zustand state (in-memory). This means the token is held in JavaScript memory only and is automatically discarded when the browser tab is closed or the page is refreshed. There is no automatic persistence to localStorage or cookies unless the frontend is explicitly configured to do so.

Call POST /api/auth/login and receive the data.token string in the response.

Store the token

Save the token in your Zustand auth store (or equivalent state manager). For persistent sessions across page refreshes, also write it to localStorage and rehydrate on startup.

Attach to requests

Add Authorization: Bearer <token> to every API call that targets a protected route.

Handle 401 responses

If any request returns 401, clear the stored token and redirect the user to the login screen to re-authenticate.

Logout

Call POST /api/auth/logout to notify the server (optional but good practice), then clear the token from state and any persisted storage.

Overview

Endpoints

Authenticating with the Spartans Gym API

How Bearer Authentication Works

Token Payload

Token Expiry

Endpoints

Request Body

Success Response `200`

Error Responses

GET /api/auth/me

Success Response `200`

Error Responses

POST /api/auth/logout

Success Response `200`

Frontend Token Storage

Build docs developers (and LLMs) love

Overview

Endpoints

Documentation Index

​How Bearer Authentication Works

​Token Payload

​Token Expiry

​Endpoints

​POST /api/auth/login

​Request Body

​Success Response 200

​Error Responses

​GET /api/auth/me

​Success Response 200

​Error Responses

​POST /api/auth/logout

​Success Response 200

​Frontend Token Storage

Build docs developers (and LLMs) love

How Bearer Authentication Works

Token Payload

Token Expiry

Endpoints

POST /api/auth/login

Request Body

Success Response `200`

Error Responses

GET /api/auth/me

Success Response `200`

Error Responses

POST /api/auth/logout

Success Response `200`

Frontend Token Storage