Set Username

Claims the authenticated user's username. Requires the `user:write` scope when called with an API key. The username is the public identifier in share-link URLs (`/share/{username}/{slug}`) and, for accounts holding `custom_subdomain`, the published-portfolio subdomain — so a user cannot create a share link until one is set. **A username can only be set once.** Once the account has one, this endpoint rejects any different value with `409 Username is locked and cannot be changed`. Re-sending the value the account already holds is a no-op and returns `200`, so the call is safe to retry. The submitted value is **normalised before validation**: lowercased, non-`[a-z0-9_-]` characters folded to hyphens, leading/trailing hyphens stripped, and truncated to 32 characters. `Jane.Doe` and `jane-doe` therefore claim the same username. It must survive normalisation as 3–32 characters and must not be a reserved word (`admin`, `api`, `app`, `docs`, and similar platform-owned names). Check with `GET /users/{username}/availability` before committing. A successful claim invalidates the caller's cached session so the new username is visible immediately rather than at the end of the session-cache TTL.

curl -X PUT "https://example.com/api/v1/users/me/username" \  -H "Content-Type: application/json" \  -d '{    "username": "veriworkly-user"  }'

{  "success": true,  "message": "Username updated successfully",  "data": {    "id": "cmnu7awv4000063lk18zpon2m",    "name": "VeriWorkly User",    "username": "veriworkly-user",    "email": "[email protected]",    "emailVerified": true,    "autoSyncEnabled": false,    "createdAt": "2026-04-11T10:37:35.584Z",    "updatedAt": "2026-04-26T02:00:00.000Z",    "_count": {      "apiKeys": 2,      "shareLinks": 4,      "resumes": 4    }  }}