Change Username

PATCH /api/v1/users/username — 🔑 Bearer · Rate limit: 5 req / hour

Sets or rotates User.username. Format-validates against admin-configurable bounds (site.username_min_length, site.username_max_length, default 3–30, lowercase alphanumeric + ._-), enforces a per-user cooldown after each change (username.change_cooldown_days, default 30), checks the desired value against active users + the reserved-name list, and writes a UsernameHistory row for audit.

Request

Body — ChangeUsernameDto

Response

200 OK — SuccessOnlyResponseDto

{
  "success": true
}

Errors

Side effects

1. Normalize submitted value (.toLowerCase().trim()).
2. Length check against site.username_min_length / site.username_max_length (admin-managed defaults 3 / 30).
3. Format check against ^[a-z0-9._-]+$.
4. Lookup User; throw not_found if missing.
5. Determine isFirstSet = (user.username === null). Cooldown checks below skip when first-set.
6. Reject if value equals current username (username_same).
7. Cooldown check — read usernameHistory (most recent changedAt); if within username.change_cooldown_days (default 30), throw username_cooldown with { daysLeft }.
8. Availability check — prisma.user.findUnique({ where: { username } }) AND prisma.reservedUsername.findUnique; throw username_taken if either hits.
9. Inside one transaction:
   • Insert UsernameHistory { oldUsername, newUsername, changedAt: now() }.
   • Update User.username = normalized.
   • Referral code sync (see section below).
   • On Prisma P2002 (concurrent claim race), throw username_taken.
10. Audit log: [username] Changed: <old> → <new> (user {userId}).

Referral code side-effect

Inside the same transaction that updates User.username, the server may also update the user's ReferralLink.code so the shareable URL stays in sync with the new username. The previous code is preserved as a ReferralLinkAlias row, so anything previously shared as bio.re/ref/<oldcode> keeps resolving to the same ReferralLink and credits the original referrer indefinitely.

Algorithm

1. Inside the same prisma.$transaction callback that wrote the UsernameHistory row and updated User.username:
2. tx.referralLink.findUnique({ where: { userId } }) — if no link exists, or link.code !== oldUsername, return (nothing to sync; non-vanity code or first-time username set).
3. Cross-table collision check for the new username, run as one Promise.all:
   • tx.referralLink.findFirst({ where: { code: normalized, NOT: { userId } } }) — another user already owns a ReferralLink with this code.
   • tx.referralLinkAlias.findUnique({ where: { code: normalized } }) — code is reserved by an alias (anyone's previous vanity code).
   • tx.user.findUnique({ where: { referralCode: normalized } }) — code clashes with someone's User.referralCode.
4. If any of the three hit, log [username] Referral code sync skipped due to collision: <code> (user <userId>) at warn level and return (username change still commits).
5. Otherwise:
   • tx.referralLinkAlias.create({ id, referralLinkId: link.id, code: link.code }) — preserve the old code.
   • tx.referralLink.update({ where: { id: link.id }, data: { code: normalized } }) — repoint the live code.
   • Log [username] Referral code synced: <old> → <new> (alias preserved) for user <userId>.

Implications for clients

• After a vanity-code rename, both bio.re/ref/<oldcode> and bio.re/ref/<newcode> continue to resolve to the same ReferralLink. Clicks on either URL increment the same ReferralLink.clicks counter — no double-counting (the alias row carries no counters of its own; it just maps code → referralLinkId).
• GET /referral/link will now return the new vanity code; previously copied/printed links remain valid via the alias.
• An alias once created is permanent for the life of the ReferralLink (deleted only by onDelete: Cascade when the link itself is deleted). A username can be claimed multiple times across renames, producing one alias per vanity rename.
• A username that was previously someone's vanity (now an alias) is not claimable as a new vanity referral code by another user — but the username change itself is unaffected, since the User.username uniqueness check (step 8 above) only consults the User table, not ReferralLink / ReferralLinkAlias. The collision only blocks the referral-code repoint.

Code samples

curl -X PATCH https://api.bio.re/api/v1/users/username \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"username": "johndoe"}'

type UsernameError = {
  code:
    | 'error.user.username_length'
    | 'error.user.username_format'
    | 'error.user.username_same'
    | 'error.user.username_cooldown'
    | 'error.user.username_taken'
    | 'error.user.not_found';
  daysLeft?: number;     // present when code === 'error.user.username_cooldown'
  minLen?: number;       // present when code === 'error.user.username_length'
  maxLen?: number;       // present when code === 'error.user.username_length'
};

async function changeUsername(accessToken: string, username: string): Promise<void> {
  const res = await fetch('https://api.bio.re/api/v1/users/username', {
    method: 'PATCH',
    headers: {
      Authorization: `Bearer ${accessToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ username }),
  });
  const json = await res.json();
  if (!res.ok || !json.success) {
    throw Object.assign(new Error(json?.error?.message ?? 'Change username failed'), {
      code: json?.error?.code,
      daysLeft: json?.error?.daysLeft,
      minLen: json?.error?.minLen,
      maxLen: json?.error?.maxLen,
    });
  }
}

import { useMutation, useQueryClient } from '@tanstack/react-query';

export function useChangeUsername() {
  const qc = useQueryClient();
  return useMutation({
    mutationFn: async (username: string) => {
      const res = await fetch('/api/v1/users/username', {
        method: 'PATCH',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ username }),
      });
      const json = await res.json();
      if (!res.ok || !json.success) {
        throw Object.assign(new Error(json?.error?.message ?? 'Change username failed'), {
          code: json?.error?.code,
          i18nKey: json?.error?.i18nKey,
          // Cooldown errors carry daysLeft for UI rendering
          daysLeft: json?.error?.daysLeft,
        });
      }
    },
    onSuccess: () => {
      qc.invalidateQueries({ queryKey: ['users', 'profile'] });
      qc.invalidateQueries({ queryKey: ['auth', 'me'] });
    },
  });
}

Try it

curl -X PATCH "https://loading/api/v1/users/username" \  -H "Content-Type: application/json" \  -d '{    "username": "string"  }'

{
  "success": true
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

{
  "success": false,
  "error": {
    "code": "AUTH_UNAUTHORIZED",
    "message": "Invalid credentials",
    "i18nKey": "auth.login.invalid_credentials",
    "i18nVars": {
      "field": "email"
    },
    "details": [
      {
        "message": "email must be an email"
      }
    ],
    "correlationId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Source