Shuffly API (1.0.0)

Send the refresh token in the JSON body as { "refreshToken": "..." }. For clients that prefer the header convention, Authorization: Bearer <refreshToken> is accepted as a fallback. The body takes precedence when both are present — this prevents auto-attached JWT Bearer headers (common in mobile HTTP clients) from being mistakenly treated as a refresh credential.

Send the refresh token in the JSON body as { "refreshToken": "..." }. For clients that prefer the header convention, Authorization: Bearer <refreshToken> is accepted as a fallback. The body takes precedence when both are present.

Mobile sign-in via a Google ID token obtained by the client through the google_sign_in Flutter package. The server verifies the token's signature against Google's JWKS, asserts iss and aud, and on first sign-in creates a users row with a synthetic +999... callerid plus matching user_identities and user_profiles rows. Returns the same token bundle as the OTP login path so downstream code is identical. Public — no JWT required (this IS the login).

Mobile sign-in via an Apple identity token obtained by the client through the sign_in_with_apple Flutter package. The server verifies the token against Apple's JWKS, asserts iss=https://appleid.apple.com and the configured bundle ID as aud, then creates or returns a user as with Google. Apple emits the user's name only on the very first sign-in, so the client may pass givenName/familyName as a fallback for display_name. The user's email may be a private-relay address; this is reported via profile.isPrivateRelay. Public — no JWT required (this IS the login).

Generates a 6-digit code, hashes and stores it in otp_requests, then sends it via SMS (vendor-specific routing for 90* numbers). Rate-limited: one send per phone per otp_resend_cooldown_seconds (system_config knob, default 60), and at most otp_max_hourly_requests per hour (default 10). A Memcached lock with the same TTL as the resend cooldown prevents duplicate sends from the same phone.

Public route — no JWT required. The same endpoint is the canonical "resend" surface — call it again once the cooldown has elapsed.

Successful responses include resendAvailableAtMs (epoch ms) — the earliest time at which a subsequent call to this endpoint will be accepted. Clients should use it to gate a "Resend code" button. The expiresAt field is the OTP TTL (configurable via otp_ttl_minutes, default 5 minutes).

When debug_otp_return=true (system_config), the response also includes the plaintext OTP under debugOtp — never enable in production.

Validates the user-supplied OTP against the most recent unused otp_requests row for the phone. On success: creates the user if new, upserts user_identities/user_profiles, registers/refreshes user_devices if deviceId is supplied, mints JWT + refresh tokens via AuthTokenService, and writes a user_sessions row.

Public route — no JWT required (this IS the login).

/otpCheck is an alias for the same handler, kept for legacy clients.

Same handler as /otpSmsCheck. Legacy alias.

Updates whitelisted columns on users (callerid, status, is_deleted, last_login_at) and/or user_profiles (username, full_name, gender, second_language, birth_date, avatar_id, bio, rating). userId (users.id) is required.

Setting avatar_id is ownership-gated — the caller must already own the target avatar (purchase via POST /v1/avatars/{avatarId}/buy first). Invalid or unowned ids return 403 / 404.

The old free-text avatar_url field was dropped — avatar_url is now a derived response field emitted via JOIN from user_profiles.avatar_id → avatars.image_url.

Most mobile clients should use /userUpdateProfile (profile-only, with stricter validation) — this endpoint is the broader admin variant.

Setting username claims a public handle: it must be free (case-insensitively) and must not match the reserved ^Newbie\d+$ provisioning shape, otherwise 409 / 422. An accepted username is mirrored onto users.display_name, which is UNIQUE as well.

Profile-only update with input validation (gender enum, birth_date format YYYY-MM-DD, bio ≤ 500 chars). Empty fields are ignored — only supplied fields are touched. Inserts a user_profiles row if none exists yet.

birth_date is never required, and it is clearable: sending the key with an explicit null writes NULL — "no selection".

An empty string is not a clear. "" keeps its legacy "not supplied" meaning and leaves the stored date alone, because the shipped Flutter client posts birthDate on every save and sends "" whenever its cached profile has no parsed date. Only null clears.

Setting avatar_id is ownership-gated — caller must own the target avatar (purchase via POST /v1/avatars/{avatarId}/buy first).

The old avatar_url/profileAvatarUrl free-text write fields are gone — avatar URL is now derived in responses via user_profiles.avatar_id → avatars.image_url JOIN.

Proxies the caller's chosen username to the AI + rule-set moderation service and returns the decision in the same request. The client calls this on submit; on approved: true it saves the profile via /userUpdateProfile (which re-verifies the approval server-side).

callerid is taken from the JWT, never the body. The moderation service is firewalled to the backend and rate-limited, so the client must NOT call it directly.

• approved: true → the name may be saved.
• approved: false + retry: true → the check could not run (service unavailable / rate-limited); the same name may be retried.
• approved: false (no retry) → rule rejection; reason (Turkish) and category explain why. Ask the user for a new name.

Availability is decided first. user_profiles.username and users.display_name are UNIQUE (case-insensitively — the columns are utf8mb4_unicode_ci). If the name is already claimed by someone else, or matches the reserved ^Newbie\d+$ provisioning shape, the response is {"approved": false, "available": false} and no AI call is made. The caller's own current name reads as available. A name that passes both gates returns available: true alongside the AI decision.

Sets users.status='deleted', is_deleted=1. Idempotent: a second call returns OK with "Hesap zaten silinmiş". Either userId or callerid is required.

Returns { countryCode, dialCode } from a hardcoded ISO-2 → dial-code map. Unknown codes default to +90.

Used by the 1-on-1 discovery feature. Pass a single userId, an array userIds[] (max 50), or pool=true to get a random batch of active users (excluding the caller). Identifier accepts numeric users.id, UUID, normalized callerid, or user_key.

In pool mode, gender (female|male) narrows the batch to that gender server-side so every returned card is usable; both or an omitted value returns a mixed pool. Ignored outside pool mode.

Returns a list of profile cards: { userId, fullName, username, bio, birthDate, gender, profileAvatarUrl, rate }. Empty list (200 or 404) when nothing matches.

Deprecated. Use GET /v1/users/{callerId}/profile instead. That endpoint is authenticated, mode-aware (private self-view vs public other-view), section-filterable, and includes gifts, cosmetics, wallet, and relationship. This endpoint is kept only for shipped client compatibility and will be removed in a future release.

Returns user + profile + interests in one call. Identifier: either callerId (or callerid) or userId (users.id). Computes age from birth_date. avatarUrl / profileAvatarUrl are derived via JOIN from user_profiles.avatar_id → avatars.image_url — the legacy free-text columns are gone. Both bio/about and profileAvatarUrl/avatarUrl are aliased in the response for client-version compatibility.

Uses the new error envelope ({ error: { code, message, details } }) unlike most legacy endpoints — see USER_IDENTIFIER_REQUIRED / USER_NOT_FOUND / GET_USER_PROFILE_FAILED.

Returns the public profile shown on a user's profile page: names, viewer's private alias for the target, avatar, rating, age, bio, interests, plus viewer-relative isFriend (bidirectional friendship edge) and isSelf flags. JWT-protected; callerId is the target user's users.callerid (digits-only, verbatim — no re-normalization). The viewer is resolved from the JWT.

Returns a user's profile shaped by mode: private (self-view, when the JWT caller is the profile target) or public (other-user view).

The mode is echoed in the response envelope. Clients use it to know what they received without re-deriving it.

/me alias

Pass callerId=me (or request GET /v1/users/me/profile) to retrieve the authenticated caller's own profile. The server resolves me to the JWT callerid and sets mode=private.

Section filtering (?include=)

Sections are opt-in via a comma-separated ?include= query param. Valid section names: core, profilePicture, cosmetics, gifts, wallet, relationship.

• Absent / empty: all sections valid for the current mode are returned.
• core: always returned, even if omitted from include.
• Private-only sections (wallet; private extras of profilePicture and cosmetics) are silently omitted in public mode — no error.
• Public-only section (relationship) is silently omitted in private mode.
• Unknown section names are silently ignored.

returnedSections in the response lists exactly which sections are present in sections.

Block gate

Before building any section the service checks the block relationship. If either the caller has blocked the target or the target has blocked the caller, the request fails with 403 PROFILE_BLOCKED and no profile body is returned.

Legacy relation

The legacy POST /getUserProfile (JWT-exempt, public, no mode concept) is deprecated and kept only for shipped client compatibility. New clients should use this endpoint.