---
title: "Profile & usernames"
description: "Reading and updating the user profile, and managing usernames."
---

> Documentation Index
> Fetch the complete documentation index at: https://truememory-docs.mvstg.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Profile & usernames

All requests go to the **Truememory Auth base URL** (see [Before you start](/authentication/overview/#before-you-start) for prerequisites: base URL, CORS whitelisting, OAuth client IDs).

## User Profile

**Get current user:**

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

Returns the same `user` object from the login response.

**Update profile:**

```bash
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.

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

**Response** (`200 OK`):

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

### Claim a username

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

```bash
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:

```json
{
  "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.

```bash
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:

```bash
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) |

:::tip[Grace period behavior]
- The old username is reserved for **14 days** after a change — no one else can claim it
- You can revert at any time during those 14 days
- After reverting, the cooldown is cleared and you can change again
- The availability check (`GET /auth/username/available`) accounts for grace-period reservations
:::

### 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.

Source: https://truememory-docs.mvstg.com/authentication/profile/index.mdx