Users Module
Manage authenticated user profiles, preferences, and account metadata.
Description
The Users module handles the core identity and profile metadata for authenticated VeriWorkly users.
While VeriWorkly is heavily designed around a local-first philosophy, users who opt into creating an account (to utilize cloud sync, resume sharing, or managed backups) interact with these endpoints to manage their platform identity.
The Local-First Boundary
To maintain strict data privacy, this module respects a clear boundary: User Identity vs. Resume Data.
The User profile returned by these endpoints only contains top-level account metadata:
- Display name and public username
- Verified email address
- Cloud sync preference (
autoSyncEnabled) - Relational counts under
_count:apiKeys,shareLinks, andresumes
Actual resume content (experience, education, templates) is never exposed through the /users
routes. That data is strictly managed via the separate Profile and Resume domains.
`_count.resumes` counts every document
Despite the name, _count.resumes counts all of the user's documents — every type, including
soft-deleted ones. It is not a count of RESUME-type documents. Use GET /documents when you need an accurate, filterable list.
Security & Access Control
| Feature | Enforcement |
|---|---|
| Authentication | A Better Auth session cookie, or an API key with the user:read / user:write scope. |
| Data Integrity | Email addresses are strictly read-only to prevent account hijacking. |
| Username immutable | A username can be claimed once. Changing it afterwards returns 409, because it is baked into existing public URLs. |
| Unauthorized Access | Requests with no valid session and no API key return 401 Unauthorized. |
Available Endpoints
GET /users/me— Get Current UserPUT /users/me/name— Update User NamePUT /users/me/username— Set UsernameGET /users/{username}/availability— Check Username AvailabilityPUT /users/me/sync— Update Auto-Sync Preference
Delete API KeyDELETE
Permanently removes an API key and its record. Use `POST /api-keys/{id}/revoke` instead if you want to keep the audit trail. `data` is `null` on success.
Get Current UserGET
Retrieves account metadata for the currently authenticated user. Requires the `user:read` scope when called with an API key. This returns identity metadata only — resume, cover letter, and portfolio content is never exposed here. Results are cached for 30 minutes and refreshed on write.