Debuta Auth API — Login, Token, and Session Restore

Debuta uses JSON Web Tokens (JWT) for session management. Local (email + password) accounts authenticate through POST /api/login, which returns a signed token valid for 7 days. Every subsequent request to a protected route must include that token in the Authorization header. Use GET /api/me at any time to exchange a valid token for the full user profile — it’s the canonical way to rehydrate a session on app launch.

Social sign-in (Google, Facebook) uses a separate flow. See Social Auth for those endpoints. Accounts created via Google or Facebook cannot authenticate through POST /api/login.

Authenticates a user with their email address and password, returning a JWT access token and the serialized user object. Auth required: No

Request body

{
  "correo": "ana@example.com",
  "password": "mySecurePass123"
}

correo

string

required

The user’s registered email address. Case-insensitive.

password

string

required

The user’s plaintext password. Minimum 6 characters. Compared against the bcrypt hash stored in the database.

Response — 200 OK

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "usuario": {
    "id": "665f1a2b3c4d5e6f78901234",
    "username": "ana_garcia1042",
    "first_name": "Ana",
    "last_name": "García",
    "correo": "ana@example.com",
    "gender": "femenino",
    "birth_date": "1998-04-12T00:00:00.000Z",
    "bio": "Amante del café y los viajes ✈️",
    "profile_picture": {
      "url": "https://res.cloudinary.com/debuta/image/upload/v1/profiles/abc123.jpg",
      "public_id": "profiles/abc123"
    },
    "photos": [],
    "interests": [
      { "name": "Senderismo", "icon": "🥾" }
    ],
    "is_verified": true,
    "rol": "user",
    "activo": true,
    "settings": { "max_distance": 50, "show_me": "ALL" }
  }
}

access_token

string

Signed JWT. Valid for 7 days (controlled by the JWT_EXPIRES_IN environment variable). Pass this in every authenticated request as Authorization: Bearer <token>.

usuario

object

The authenticated user’s serialized profile. See UserObject fields below.

Error responses

Status	Condition
`400`	`correo` or `password` missing from the request body
`401`	Wrong email or password
`401`	Account was created with Google or Facebook — use social auth
`401`	Account is deactivated (`activo: false`)
`500`	Internal server error

curl example

curl -X POST https://api.debuta.app/api/login \
  -H "Content-Type: application/json" \
  -d '{
    "correo": "ana@example.com",
    "password": "mySecurePass123"
  }'

GET /api/me

Returns the full profile of the currently authenticated user. The mobile app calls this endpoint on startup to restore the session from a stored token. Auth required: Yes — Authorization: Bearer <token>

Response — 200 OK

{
  "usuario": {
    "id": "665f1a2b3c4d5e6f78901234",
    "username": "ana_garcia1042",
    "first_name": "Ana",
    "last_name": "García",
    "correo": "ana@example.com",
    "gender": "femenino",
    "birth_date": "1998-04-12T00:00:00.000Z",
    "bio": "Amante del café y los viajes ✈️",
    "profile_picture": {
      "url": "https://res.cloudinary.com/debuta/image/upload/v1/profiles/abc123.jpg",
      "public_id": "profiles/abc123"
    },
    "cover_photo": null,
    "photos": [],
    "interests": [
      { "name": "Senderismo", "icon": "🥾" }
    ],
    "is_verified": true,
    "needs_profile_completion": false,
    "rol": "user",
    "activo": true,
    "ciudad": "Ciudad de México",
    "pais": "México",
    "location_label": "CDMX, México",
    "job_title": "Diseñadora UX",
    "company": "Startup Lab",
    "education": "UNAM",
    "buscando": "citas",
    "settings": {
      "max_distance": 50,
      "min_age": 18,
      "max_age": 40,
      "show_me": "ALL",
      "notif_matches": true,
      "notif_messages": true,
      "profile_visible": true
    },
    "createdAt": "2024-06-04T10:22:41.000Z",
    "updatedAt": "2024-11-15T08:14:09.000Z"
  }
}

usuario

object

The full user profile. See UserObject fields below.

Error responses

Status	Condition
`401`	Missing, malformed, or expired JWT
`500`	Internal server error

curl example

curl https://api.debuta.app/api/me \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

UserObject fields

The usuario object returned by both endpoints is produced by serializarUsuario(). It strips password and __v, and always includes a top-level id string alongside Mongoose’s _id.

string

MongoDB ObjectId as a string. Canonical user identifier.

username

string

Unique, lowercase handle. Auto-generated at registration from the user’s first name plus a 4-digit suffix (e.g. ana_garcia1042).

first_name

string

User’s first name.

last_name

string

User’s last name. May be an empty string for social auth accounts that didn’t provide it.

correo

string

Email address. Always lowercase.

gender

string

One of: masculino, femenino, no_binario, otro, prefiero_no_decir.

birth_date

string (ISO 8601)

Date of birth. Use the virtual age field for a pre-computed integer age.

age

number

Virtual field. Computed integer age in years from birth_date.

bio

string

Free-text profile bio. Max 500 characters.

profile_picture

object | null

Main profile photo from Cloudinary: { url: string, public_id: string }.

cover_photo

object | null

Cover / banner photo from Cloudinary: { url: string, public_id: string }.

photos

array

Gallery of up to 6 additional photos. Each item: { url: string, public_id: string }.

interests

array

Array of interest objects: { name: string, icon: string }.

is_verified

boolean

true if the account has been verified (facial photo submitted or OAuth provider verified the email).

needs_profile_completion

boolean

true for newly created OAuth accounts that haven’t set gender or birth_date yet. The app should redirect these users to a profile completion screen.

rol

string

Account role: user, admin, or asociado.

activo

boolean

false means the account has been deactivated and cannot log in.

job_title

string

Job title (e.g. "Diseñadora UX"). Max 100 characters.

company

string

Employer name. Max 100 characters.

education

string

Educational institution. Max 150 characters.

relationship_status

string

One of: single, in_relationship, married, complicated, prefer_not_say, or empty string.

website

string

Personal website URL. Max 200 characters.

buscando

string

What the user is looking for: amistad, citas, serio, casual, no_lo_se, or empty string.

religion

string

User’s religion. Free-text.

zodiac

string

Zodiac sign. Free-text.

smoke

string

Smoking habit: si, no, socialmente, ocasionalmente, or empty string.

drink

string

Drinking habit: si, no, socialmente, ocasionalmente, or empty string.

languages

array

Array of language strings (e.g. ["Español", "Inglés"]).

height

number | null

Height in centimetres.

exercise

string

Exercise frequency: siempre, a_veces, nunca, or empty string.

ciudad

string

City name (e.g. "Ciudad de México").

pais

string

Country name (e.g. "México").

location_label

string

Human-readable location label (e.g. "CDMX, México").

latitude

number | null

GPS latitude. Used for distance-based discovery.

longitude

number | null

GPS longitude.

auth_provider

string

Authentication method: local, google, or facebook.

settings

object

User’s discovery and privacy preferences. See Settings API for the full schema.

createdAt

string (ISO 8601)

Account creation timestamp.

updatedAt

string (ISO 8601)

Last update timestamp.

Authentication

Users & Profiles

Discovery & Matching

Chat & Calls

Content & Safety

Partners & Support

Debuta Auth API — Login, Token, and Session Restore

Request body

Response — 200 OK

Error responses

curl example

GET /api/me

Response — 200 OK

Error responses

curl example

UserObject fields

Build docs developers (and LLMs) love

Authentication

Users & Profiles

Discovery & Matching

Chat & Calls

Content & Safety

Partners & Support

Documentation Index

​POST /api/login

​Request body

​Response — 200 OK

​Error responses

​curl example

​GET /api/me

​Response — 200 OK

​Error responses

​curl example

​UserObject fields

Build docs developers (and LLMs) love

POST /api/login

Request body

Response — 200 OK

Error responses

curl example

GET /api/me

Response — 200 OK

Error responses

curl example

UserObject fields