Profile
PATCH /v1/auth/profile, PUT /v1/auth/username and GET /v1/auth/username/available — identity fields.
This group edits the identity fields themselves: display name and username. The extended profile (gender, birthdate, bio, metadata) lives in the account context.
PATCH /profile
| Parameter | Type | Required | Notes |
|---|---|---|---|
display_name | string | null | Optional | 1–64 chars after trimming |
Omitted fields stay unchanged; an explicit null clears the value. An empty string is rejected — "clear the name" and "send an empty string" are two different intentions, and only one of them is expressible.
{ "success": true, "display_name": "Alice" }PUT /username
| Parameter | Type | Required | Notes |
|---|---|---|---|
username | string | ✅ | 3–32 chars, trimmed and lowercased |
{ "success": true, "username": "alice" }Requires max_age=300. A username change is a takeover vector: whoever holds it next can receive mail and invitations meant for the previous owner. Step-up makes sure the change was made by someone who has just proven they are the account holder.
GET /username/available
| Query | Type | Required | Notes |
|---|---|---|---|
username | string | ✅ | Candidate, 3–32 chars |
{ "success": true, "username": "alice", "available": false, "reason": "taken" }| Field | Notes |
|---|---|
available | Whether the name can be taken right now |
reason | taken / invalid / reserved; absent when available |
Availability is a hint, not a reservation
Someone else can take the name between this check and the PUT. The authoritative answer is the PUT response; treat a conflict there as normal, not as a bug.
Step-up: why max_age but not AAL2
| Operation | Requirement | Why |
|---|---|---|
| Change display name | None | Cosmetic; nothing is lost |
| Change username | max_age=300 | Redirects traffic and identity; must be recent |
| Take a username | None beyond the above | — |
Requiring AAL2 here would lock out accounts that only have a password: they would have to enrol a second factor before they could rename themselves. The risk being defended against is "someone else acting as you", and a fresh verification answers that regardless of which method was used.
Related
- Extended profile: Account profile
- Readable identity fields for clients: User info
- Step-up: Session elevation