Profile & usernames | truememory docs

All requests go to the Truememory Auth base URL (see Before you start for prerequisites: base URL, CORS whitelisting, OAuth client IDs).

User Profile

Get current user:

GET https://your-auth-host/auth/me
Authorization: Bearer <id_token>

Returns the same user object from the login response.

Update profile:

PATCH https://your-auth-host/auth/me
Authorization: Bearer <id_token>
Content-Type: application/json

{
  "display_name": "Updated Name",
  "metadata": {"preferred_model": "anthropic/claude-sonnet-4-5"}
}

Metadata is shallow-merged: set a key to null to delete it. Max 50 keys, 16 KB total.

Usernames

Users can claim a unique username after registration. Usernames are globally unique — the same username cannot be held by two different users, regardless of tenant.

Rules

Rule	Value
Length	3-30 characters
Allowed characters	Lowercase letters, numbers, hyphens (`-`), underscores (`_`)
Case	Auto-lowercased (e.g. `JaneDoe` becomes `janedoe`)
Reserved words	`admin`, `system`, `support`, `root`, `me`, `user`, `login`, `register`, `signup`, `logout`, `settings`, `help`, `info`, `api`, `null`, `undefined`, `moderator`, `administrator`, `username`

Check availability

Check if a username is available before claiming. No authentication required.

GET https://your-auth-host/auth/username/available?username=janedoe

Response (200 OK):

{
  "username": "janedoe",
  "available": true
}

Claim a username

Claim a username for the authenticated user. A username must be claimed before it can be changed.

POST https://your-auth-host/auth/username/claim
Authorization: Bearer <id_token>
Content-Type: application/json

{
  "username": "janedoe"
}

Response (200 OK):

Returns the full user object with the username field set:

{
  "id": "4b822c30-1a07-40d6-8d59-321ef99037f6",
  "username": "janedoe",
  "email": "jane@example.com",
  "display_name": "Jane Doe",
  ...
}

Error cases:

Code	Status	When
`USER_USERNAME_TAKEN`	409	Another user already has this username
`USER_USERNAME_ALREADY_CLAIMED`	409	You already have a username — use `PUT /auth/username` to change it
`USER_USERNAME_INVALID`	422	Username fails validation (too short, invalid characters, reserved word)

Change username

Change your username after claiming one. Subject to a 14-day cooldown — you can only change your username once every 14 days.

When you change your username, the old one is reserved for 14 days (grace period). During this window, no one else can take it, and you can revert to it. After 14 days, the old username becomes available to other users.

PUT https://your-auth-host/auth/username
Authorization: Bearer <id_token>
Content-Type: application/json

{
  "username": "new_handle"
}

Response (200 OK):

Returns the full user object with the updated username.

Error cases:

Code	Status	When
`USER_USERNAME_TAKEN`	409	Another user already has this username, or it is reserved in a grace period
`USER_USERNAME_COOLDOWN`	400	You changed your username within the last 14 days — wait for the cooldown to expire
`USER_USERNAME_INVALID`	409	You haven’t claimed a username yet — use `POST /auth/username/claim` first

Revert to previous username

During the 14-day grace period after a username change, you can revert to your previous username:

POST https://your-auth-host/auth/username/revert
Authorization: Bearer <id_token>

Response (200 OK):

Returns the full user object with the reverted username.

Error cases:

Code	Status	When
`USER_USERNAME_NO_REVERTIBLE`	404	No previous username to revert to (grace period may have expired)

Reading the username

The username field is included in all user responses: GET /auth/me, login, registration, and OAuth sign-in responses. It is null until claimed.