Users & Authentication API Reference

WayFy’s Users API handles everything from account creation and login to profile management and saved favorite places. Each user can store a selected_mobility profile — an array of mobility preferences used to tailor accessibility results across the platform. Favorites let users bookmark accessible places discovered on the map and attach rich metadata for later use in trip planning.

All protected endpoints require a JWT bearer token obtained from /api/users/login or /api/users/register. Include it as Authorization: Bearer <token> in the request header.

Authentication

POST /api/users/register

Creates a new WayFy account and immediately returns a JWT token so users can begin exploring without a separate login step. All six fields are required — confirmPassword must match password, and selectedMobility must contain at least one option. Authentication: None

Request

string

required

The user’s email address. Must be unique across all WayFy accounts.

password

string

required

Plain-text password. Must be at least 8 characters. Stored as a bcrypt hash — never logged or returned.

confirmPassword

string

required

Must match password exactly. The server rejects the request if they differ.

firstname

string

required

User’s first name. Displayed in the app profile.

lastname

string

required

User’s last name.

selectedMobility

array

required

At least one mobility preference string (e.g. ["wheelchair"]). The server rejects empty arrays.

Response

msg

string

Confirmation message.

token

string

Signed JWT for authenticating subsequent requests.

expiresIn

integer

Token lifetime in seconds (e.g. 3600 for 1 hour).

user

object

Show User object

integer

Unique user ID.

string

Registered email address.

firstname

string

First name.

lastname

string

Last name.

avatar

string

Full avatar path, e.g. /api/users/avatar/default_avatar.png.

selected_mobility

array

JSON array of mobility preference strings.

is_active

boolean

Whether the account is active.

is_admin

boolean

Whether the account has admin privileges.

Example

curl -X POST http://localhost:3001/api/users/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@wayfy.app",
    "password": "securepassword",
    "confirmPassword": "securepassword",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "selectedMobility": ["wheelchair"]
  }'

{
  "msg": "Usuario registrado correctamente",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": 42,
    "email": "ada@wayfy.app",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "avatar": "/api/users/avatar/default_avatar.png",
    "selected_mobility": ["wheelchair"],
    "is_active": true,
    "is_admin": false
  }
}

Authenticates an existing user with email and password, returning a fresh JWT token. Authentication: None

Request

string

required

The account’s registered email address.

password

string

required

The account’s password in plain text.

Response

msg

string

Confirmation message.

token

string

Signed JWT for authenticating subsequent requests.

expiresIn

integer

Token lifetime in seconds.

user

object

Show User object

integer

Unique user ID.

string

Registered email address.

firstname

string

First name.

lastname

string

Last name.

avatar

string

Full avatar path, e.g. /api/users/avatar/default_avatar.png.

selected_mobility

array

Saved mobility preferences.

is_active

boolean

Account active status.

is_admin

boolean

Admin flag.

Returns 401 Unauthorized if the email is not found or the password does not match. Returns 403 Forbidden if the account is inactive.

Example

curl -X POST http://localhost:3001/api/users/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "ada@wayfy.app",
    "password": "securepassword"
  }'

{
  "msg": "Autenticado correctamente",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": 42,
    "email": "ada@wayfy.app",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "avatar": "/api/users/avatar/default_avatar.png",
    "selected_mobility": ["wheelchair", "low_floor"],
    "is_active": true,
    "is_admin": false
  }
}

User Profiles

GET /api/users/

Returns all user records. Admin only — non-admin requests receive 403 Forbidden. Authentication: Required (admin only)

Response

total

integer

Total number of users returned.

users

array

Array of all user objects.

Show User object

integer

Unique user ID.

string

Email address.

firstname

string

First name.

lastname

string

Last name.

avatar

string

Full avatar path.

selected_mobility

array

Mobility preference array.

is_active

boolean

Account active status.

is_admin

boolean

Admin flag.

Example

curl http://localhost:3001/api/users/ \
  -H "Authorization: Bearer <admin-token>"

{
  "total": 1,
  "users": [
    {
      "id": 42,
      "email": "ada@wayfy.app",
      "firstname": "Ada",
      "lastname": "Lovelace",
      "avatar": "/api/users/avatar/default_avatar.png",
      "selected_mobility": ["wheelchair"],
      "is_active": true,
      "is_admin": false
    }
  ]
}

GET /api/users/:user_id

Returns a single user record. Regular users may only fetch their own profile; admins may fetch any user. Authentication: Required

Response

integer

Unique user ID.

string

Email address.

firstname

string

First name.

lastname

string

Last name.

avatar

string

Full avatar path, e.g. /api/users/avatar/default_avatar.png.

selected_mobility

array

Saved mobility preference strings.

is_active

boolean

Account active status.

is_admin

boolean

Admin flag.

Example

curl http://localhost:3001/api/users/42 \
  -H "Authorization: Bearer <token>"

{
  "id": 42,
  "email": "ada@wayfy.app",
  "firstname": "Ada",
  "lastname": "Lovelace",
  "avatar": "/api/users/avatar/default_avatar.png",
  "selected_mobility": ["wheelchair", "low_floor"],
  "is_active": true,
  "is_admin": false
}

PUT /api/users/:user_id

Updates profile fields for a user. Regular users may only update their own account; admins can update any account. Returns a fresh JWT token alongside the updated user object. Authentication: Required

Request

firstname

string

Updated first name.

lastname

string

Updated last name.

string

New email address. Must remain unique across all accounts.

selectedMobility

array

Replacement array of mobility preference strings (e.g. ["wheelchair", "low_floor"]). Overwrites the current value.

password

string

New password. Must be at least 8 characters. Leave absent to keep the current password.

Response

Returns the full updated user object plus a refreshed token.

msg

string

Confirmation message.

token

string

New JWT reflecting updated profile claims.

expiresIn

integer

Token lifetime in seconds.

user

object

Full updated user object.

Example

curl -X PUT http://localhost:3001/api/users/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "firstname": "Ada",
    "selectedMobility": ["wheelchair", "low_floor", "visual_impairment"]
  }'

{
  "msg": "Usuario actualizado correctamente",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": 42,
    "email": "ada@wayfy.app",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "avatar": "/api/users/avatar/default_avatar.png",
    "selected_mobility": ["wheelchair", "low_floor", "visual_impairment"],
    "is_active": true,
    "is_admin": false
  }
}

DELETE /api/users/:user_id

Permanently deletes a user account and all associated data. Regular users may only delete their own account; admins can delete any account except their own. Authentication: Required

This action is irreversible. Deleting an account removes the user’s trips, favorites, and accessibility contributions.

Example

curl -X DELETE http://localhost:3001/api/users/42 \
  -H "Authorization: Bearer <token>"

{
  "msg": "Usuario eliminado correctamente"
}

Avatars

PUT /api/users/avatar

Uploads a new avatar image for the authenticated user. Send the file as multipart/form-data using the field name file. Accepted formats: png, jpg, jpeg. Returns a refreshed JWT alongside the updated user object. Authentication: Required

Request

file

required

Image file to use as the user’s avatar. Accepted formats: png, jpg, jpeg. Sent as multipart/form-data.

Response

Returns a refreshed token and the updated user object with the new avatar path.

msg

string

Confirmation message.

token

string

New JWT with updated avatar claim.

expiresIn

integer

Token lifetime in seconds.

user

object

Full updated user object including the new avatar path.

Example

curl -X PUT http://localhost:3001/api/users/avatar \
  -H "Authorization: Bearer <token>" \
  -F "file=@/path/to/photo.jpg"

{
  "msg": "Avatar actualizado correctamente",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 3600,
  "user": {
    "id": 42,
    "email": "ada@wayfy.app",
    "firstname": "Ada",
    "lastname": "Lovelace",
    "avatar": "/api/users/avatar/avatar_user_42_1712345678.jpg",
    "selected_mobility": ["wheelchair"],
    "is_active": true,
    "is_admin": false
  }
}

GET /api/users/avatar/:filename

Serves an avatar image file by its stored filename. Use this URL as the src for avatar <img> elements in the WayFy frontend. Authentication: Required

Example

curl http://localhost:3001/api/users/avatar/avatar_user_42_1712345678.jpg \
  -H "Authorization: Bearer <token>" \
  --output avatar.jpg

Favorites

Favorites allow users to bookmark accessible places found on the WayFy map. Each favorite stores rich metadata — coordinates, OpenStreetMap identifiers, wheelchair status, and full OSM tags — making them immediately usable when building trip itineraries.

GET /api/users/:user_id/favorites

Returns all saved favorite places for the specified user. Authentication: Required

Response

total

integer

Number of favorites returned.

favorites

array

Show Favorite object

integer

Favorite record ID.

user_id

integer

Owning user’s ID.

osm_id

string

OpenStreetMap identifier for the place.

place_name

string

Human-readable place name.

place_label

string

Short descriptive label (e.g. city + country).

longitude

number

Place longitude.

latitude

number

Place latitude.

wheelchair

string

Wheelchair accessibility: yes, limited, or no.

osm_type

string

OSM element type: node, way, or relation.

sub_type

string

WayFy place category (e.g. gastronomia, transporte).

all_tags

object

Full OSM tag set as a JSON object.

created_at

string

ISO 8601 timestamp when the favorite was saved.

Example

curl http://localhost:3001/api/users/42/favorites \
  -H "Authorization: Bearer <token>"

{
  "total": 1,
  "favorites": [
    {
      "id": 7,
      "user_id": 42,
      "osm_id": "node/123456789",
      "place_name": "Café Inclusivo",
      "place_label": "Madrid, Spain",
      "longitude": -3.70325,
      "latitude": 40.41650,
      "wheelchair": "yes",
      "osm_type": "node",
      "sub_type": "gastronomia",
      "all_tags": { "amenity": "cafe", "wheelchair": "yes", "name": "Café Inclusivo" },
      "created_at": "2024-04-05T14:22:00Z"
    }
  ]
}

POST /api/users/:user_id/favorites

Saves a new place to the user’s favorites. The osm_id + user_id combination must be unique — attempting to re-save the same place returns an error. Authentication: Required

Request

osm_id

string

required

OpenStreetMap identifier for the place (e.g. node/123456789).

place_name

string

Human-readable name of the place.

place_label

string

Short location label (e.g. Barcelona, Spain).

longitude

number

Longitude coordinate.

latitude

number

Latitude coordinate.

wheelchair

string

Wheelchair accessibility value from OSM: yes, limited, or no.

osm_type

string

OSM element type: node, way, or relation.

sub_type

string

WayFy place category (e.g. gastronomia, cultura_turismo).

all_tags

object

Full OSM tag set as a JSON object. Stored for rich detail display in WayFy.

Response

Returns 201 Created with a wrapper object containing the new favorite.

msg

string

Confirmation message.

favorite

object

The newly created favorite object (same shape as the GET response items).

Example

curl -X POST http://localhost:3001/api/users/42/favorites \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "osm_id": "node/123456789",
    "place_name": "Café Inclusivo",
    "place_label": "Madrid, Spain",
    "longitude": -3.70325,
    "latitude": 40.41650,
    "wheelchair": "yes",
    "osm_type": "node",
    "sub_type": "gastronomia",
    "all_tags": { "amenity": "cafe", "wheelchair": "yes" }
  }'

{
  "msg": "Favorito agregado correctamente",
  "favorite": {
    "id": 7,
    "user_id": 42,
    "osm_id": "node/123456789",
    "place_name": "Café Inclusivo",
    "place_label": "Madrid, Spain",
    "longitude": -3.70325,
    "latitude": 40.41650,
    "wheelchair": "yes",
    "osm_type": "node",
    "sub_type": "gastronomia",
    "all_tags": { "amenity": "cafe", "wheelchair": "yes" },
    "created_at": "2024-04-05T14:22:00Z"
  }
}

DELETE /api/users/:user_id/favorites/:osm_id

Removes a saved place from the user’s favorites by its OSM identifier. Authentication: Required

Example

curl -X DELETE http://localhost:3001/api/users/42/favorites/node%2F123456789 \
  -H "Authorization: Bearer <token>"

{
  "msg": "Favorito eliminado correctamente",
  "osm_id": "node/123456789"
}

Overview

Endpoints

Documentation Index

​Authentication

​POST /api/users/register

​Request

​Response

​Example

​POST /api/users/login

​Request

​Response

​Example

​User Profiles

​GET /api/users/

​Response

​Example

​GET /api/users/:user_id

​Response

​Example

​PUT /api/users/:user_id

​Request

​Response

​Example

​DELETE /api/users/:user_id

​Example

​Avatars

​PUT /api/users/avatar

​Request

​Response

​Example

​GET /api/users/avatar/:filename

​Example

​Favorites

​GET /api/users/:user_id/favorites

​Response

​Example

​POST /api/users/:user_id/favorites

​Request

​Response

​Example

​DELETE /api/users/:user_id/favorites/:osm_id

​Example

Build docs developers (and LLMs) love

Authentication

POST /api/users/register

Request

Response

Example

POST /api/users/login

Request

Response

Example

User Profiles

GET /api/users/

Response

Example

GET /api/users/:user_id

Response

Example

PUT /api/users/:user_id

Request

Response

Example

DELETE /api/users/:user_id

Example

Avatars

PUT /api/users/avatar

Request

Response

Example

GET /api/users/avatar/:filename

Example

Favorites

GET /api/users/:user_id/favorites

Response

Example

POST /api/users/:user_id/favorites

Request

Response

Example

DELETE /api/users/:user_id/favorites/:osm_id

Example