A free and open source instant messaging and VoIP chat app built for friends, groups, and communities.
docs: document verification levels, claiming and date of birth
Hampus623e27b20fd0
diff --git a/fluxer_docs/src/content/docs/authentication.md b/fluxer_docs/src/content/docs/authentication.mdindex 37e31c0e5..c268a039a 100644--- a/fluxer_docs/src/content/docs/authentication.md+++ b/fluxer_docs/src/content/docs/authentication.md@@ -113,7 +113,6 @@ An instance can enforce single sign-on once it is configured and enabled. While- [Register an account](/http-api/authentication/#register-an-account) and [Log in with a password](/http-api/authentication/#log-in-with-a-password).- [Get discoverable WebAuthn options](/http-api/authentication/#get-discoverable-webauthn-options) and [Authenticate with WebAuthn](/http-api/authentication/#authenticate-with-webauthn).- [Complete login with TOTP](/http-api/authentication/#complete-login-with-totp), [Get WebAuthn MFA options](/http-api/authentication/#get-webauthn-mfa-options), and [Complete login with WebAuthn MFA](/http-api/authentication/#complete-login-with-webauthn-mfa).-- [Start passkey bridge sign-in](/http-api/authentication/#start-passkey-bridge-sign-in) and [Redeem passkey bridge sign-in](/http-api/authentication/#redeem-passkey-bridge-sign-in).- [Verify an email address](/http-api/authentication/#verify-an-email-address) and [Resend email verification](/http-api/authentication/#resend-email-verification).- [Request password recovery](/http-api/authentication/#request-password-recovery), [Validate a password reset token](/http-api/authentication/#validate-a-password-reset-token), and [Reset a password](/http-api/authentication/#reset-a-password).- [Revert an email change](/http-api/authentication/#revert-an-email-change).@@ -122,12 +121,14 @@ An instance can enforce single sign-on once it is configured and enabled. WhileThe single sign-on callback returns the same code when the provider claims match no existing account and the instance does not auto-provision.-Enforcement applies at those operations only, and does not gate password change or multi-factor management on an already authenticated account. Enabling it leaves an already issued session token, bot token, OAuth2 access token, or Admin API key valid.+An account linked to the provider also loses its own credentials while enforcement is active. Every [email change](/http-api/users/email-and-password/) and password change operation returns 403 `SSO_REQUIRED` for it, and so does [Update current user](/http-api/users/current-user/) when the body sets `new_password` or `email_token`. Profile edits and multi-factor management stay open, and an account with no provider link keeps its email and password operations. On an instance where people sign in with an email, each sign-in through the provider replaces the account email with the verified email the provider sends, unless another account already holds that address. Enabling it leaves an already issued session token, bot token, OAuth2 access token, or Admin API key valid.## Account state gatesA [limited account](/http-api/users/#account-limitation) keeps its credentials and sessions. The operations listed there return 403 `ACCOUNT_LIMITED`, and every other operation accepts the account as usual.+An account that still has to [set its date of birth](/http-api/users/current-user/#set-date-of-birth) gets 403 `DATE_OF_BIRTH_REQUIRED` from most operations until it does. An account that is not yet verified can be refused operations that reach other people, as described under [account tiers](/http-api/users/#account-tiers).+No shared gate rejects a deleted or disabled account. Each operation that reads account state applies its own rule, and login, password, and email operations refuse a deleted account outright.## Failed authentication@@ -142,7 +143,7 @@ Sudo mode is a short-lived proof that the account holder recently re-verified aA sudo proof lasts five minutes. Present it in the `X-Fluxer-Sudo-Mode-JWT` request header. An invalid, expired, or account-mismatched token produces the same response as a missing one.-Fluxer issues a token only for an account holding a TOTP secret or a registered WebAuthn credential, so a password-only account re-verifies for each operation that requires sudo mode. A passkey counts here whether or not the account enabled passkeys as a second factor. The `methods` object reports `totp`, `webauthn`, and `backup_codes`, and an account holding no TOTP secret presents an unconsumed backup code under `mfa_method` of `totp`. [Create WebAuthn registration options](/http-api/users/mfa/#create-webauthn-registration-options) and [Disable current account](/http-api/users/current-user/#disable-current-account) issue no sudo token and return no `X-Fluxer-Sudo-Mode-JWT` response header, even for an account that can prove a credential. A bot account satisfies sudo mode immediately. So does an account that has no password, no TOTP secret, and no registered WebAuthn credential.+Fluxer issues a token for an account holding a TOTP secret or a registered WebAuthn credential, and after an emailed code. A password-only account that proves sudo mode with its password re-verifies for each operation that requires it. A passkey counts here whether or not the account enabled passkeys as a second factor. The `methods` object reports `totp`, `webauthn`, and `backup_codes`, and an account holding no TOTP secret presents an unconsumed backup code under `mfa_method` of `totp`. [Create WebAuthn registration options](/http-api/users/mfa/#create-webauthn-registration-options) and [Disable current account](/http-api/users/current-user/#disable-current-account) issue no sudo token and return no `X-Fluxer-Sudo-Mode-JWT` response header, even for an account that can prove a credential. A bot account satisfies sudo mode immediately. So does an account that has no password, no TOTP secret, no registered WebAuthn credential and no confirmed email address. An account without those but with a confirmed address proves sudo mode with an [emailed code](/http-api/users/mfa/#send-a-sudo-email-code).:::note[A sudo proof covers every account session]Revoking the session that obtained a proof leaves that proof valid until it expires.diff --git a/fluxer_docs/src/content/docs/http-api/users.mdx b/fluxer_docs/src/content/docs/http-api/users.mdxindex b411f00ae..1f1e388bb 100644--- a/fluxer_docs/src/content/docs/http-api/users.mdx+++ b/fluxer_docs/src/content/docs/http-api/users.mdx@@ -38,6 +38,8 @@ The public account representation embedded by messages, relationships, guild mem<sup>1</sup> An animated avatar hash has the `a_` prefix, and the prefix is removed while the account has no animated avatar entitlement+On an instance that applies the [account tiers](#account-tiers), an account that cannot yet reach other people shows them only its username and discriminator. `global_name` and `avatar` are null in every partial user that other accounts read, and the account's own reads are unchanged.+### Example```json@@ -151,7 +153,13 @@ The private representation of the current account, returned by [Get current user| pending_bulk_message_deletion<sup>3</sup> | ?[pending bulk message deletion](#pending-bulk-message-deletion-object) object | The message deletion the account scheduled for itself, or null when none is pending || age_verified_adult? | boolean | Whether adult age verification is complete, omitted when false || terms_agreed_at | ?ISO8601 timestamp | The time of the most recent terms acceptance, or null |-| privacy_agreed_at | ?ISO8601 timestamp | The time of the most recent privacy policy acceptance, or null |+| privacy_agreed_at | ?ISO8601 timestamp | The time the account was last shown the current privacy policy, or null |+| claimed? | boolean | Whether the account can be signed in to from another device, through a confirmed email, a password or a passkey |+| account_tier? | string | The [account tier](#account-tiers), one of `unclaimed`, `unverified` or `verified` |+| verification_need?<sup>18</sup> | ?string | What the account still has to do to become verified, or null once it is |+| has_password? | boolean | Whether the account has a password |+| date_of_birth_required?<sup>17</sup> | boolean | Whether the account still has to [set its date of birth](/http-api/users/current-user/#set-date-of-birth). Clients ask for it before anything else |+| profile_restricted? | boolean | Whether other accounts see only the username and discriminator, as described under [account tiers](#account-tiers) |<sup>1</sup> An animated avatar hash has the `a_` prefix, and the prefix is removed while the account has no animated avatar entitlement@@ -185,6 +193,11 @@ The private representation of the current account, returned by [Get current user<sup>16</sup> Reports whether unread gifts exist and how many. An account with no gifts reports `false` and `0`+<sup>17</sup> True for every account without a date of birth on an instance that collects dates of birth. When the [accounts configuration](/admin-api/instance/#accounts-configuration-object) enforces the date for the account, every route except a short list returns 403 `DATE_OF_BIRTH_REQUIRED`, and the Gateway reports no guilds for the account. The list is get current user, set date of birth, get current user settings, the account disable and delete routes, accept current policies, the data harvest routes, the experiment assignments and get Gateway, plus every authentication and sudo route++<sup>18</sup> One of `add_email`, `confirm_email` or `password`. The same value is the `need` in an `ACCOUNT_VERIFICATION_REQUIRED` [error response](/http-api/#error-response)++:::note[A bearer read returns zero values]`acls`, `traits`, and `required_actions` become empty arrays. `email_bounced` and `authenticator_types` are dropped. Every field marked <sup>3</sup> above that is a boolean becomes `false`, every timestamp or nullable field becomes `null`, and `unread_gift_inventory_count` becomes `0`.:::@@ -210,10 +223,6 @@ A scheduled deletion of every message the account has sent. The field is this ob| 0 | TOTP | Time-based one-time password authenticator || 2 | WEBAUTHN | WebAuthn authenticator |-The value `1` is unassigned. Any stored authenticator value outside this registry is excluded from `authenticator_types`.--`WEBAUTHN` is present only while the account chose passkeys as a second factor through [Set WebAuthn two-factor authentication](/http-api/users/mfa/#set-webauthn-two-factor-authentication). Registering a credential does not add it, so an account can hold passkeys without the type.-## Premium types| Value | Name | Description |@@ -239,6 +248,35 @@ An account is limited while its [user object](#user-object) reports `account_lim- [Initiate connection](/http-api/connections/#initiate-connection), [Verify and create connection](/http-api/connections/#verify-and-create-connection), and [Start Bluesky authorisation](/http-api/connections/#start-bluesky-authorisation)- [Upload entrance sound](/http-api/entrance-sounds/#upload-entrance-sound) and [Set entrance sound selection](/http-api/entrance-sounds/#set-entrance-sound-selection)+## Account tiers++Every account is in one of three tiers. It is unclaimed while it has no email address on an instance that signs in with email. It is unverified while its email address is not confirmed. Every other account is verified. On a `username` instance, and on an instance that sends no email, an account with a password or a passkey counts as verified and one without counts as unclaimed.++An instance chooses with `interaction_tier` in its [accounts configuration](/admin-api/instance/#accounts-configuration-object) how the tiers apply. In `legacy` mode the earlier email verification rules stay as they were. In `enforced` mode an account that is not verified can read, edit its own profile and settings, write personal notes, and join communities, but cannot do anything that reaches another person. Those operations fail with an error that names what is missing. An action that had its own error code before keeps it, such as `UNCLAIMED_ACCOUNT_CANNOT_SEND_MESSAGES` or `EMAIL_VERIFICATION_REQUIRED`, so older clients still understand it. Every other action returns 403 `ACCOUNT_VERIFICATION_REQUIRED`, with `action` and `tier` in the [error response](/http-api/#error-response).++| Action | Operations |+| --- | --- |+| `message` | Create, modify and crosspost a message, start a thread |+| `typing` | Trigger typing indicator |+| `reaction` | Add own reaction |+| `direct_message` | Open a direct message |+| `group_dm` | Create or join a group direct message |+| `friend_request` | Send a friend request |+| `friend_accept` | Accept a friend request |+| `invite_create` | Create an invite |+| `guild_create` | Create a guild |+| `voice` | Join a voice channel |+| `call` | Start or ring a call |+| `thread_join` | Join a thread |+| `channel_follow` | Follow an announcement channel |+| `ownership_transfer` | Receive guild ownership |+| `application_create` | Create an application |+| `gift_redeem` | Redeem a gift, for unclaimed accounts only |++Reports from accounts that are not verified are accepted on an `enforced` instance, up to 5 a day for each account and 10 a day for each IP address. A second report on the same target from the same network within a day is accepted and then dropped.++The join gate applies to people assigned [guild visits](/admin-api/instance/#guild-visits-configuration-object) on every client. An instance that sets `guild_join_gate` to `visits_capable` applies it only when the client sends the `X-Fluxer-Capabilities: guild_visits` request header.+## Profile field privacy flagsA field whose flags value is `0` is visible to nobody, including on the owner's own profile read.@@ -433,8 +471,6 @@ One entry of the saved, user-owned guild sidebar layout. Joining a guild prepend## Guild sensitive media filters-Guild channels accept only these values.-| Value | Name | Description || --- | --- | --- || 0 | SHOW | Show sensitive media |@@ -541,9 +577,10 @@ The profile read returned by [Get user profile](#get-user-profile) for one targe| user_profile | [user profile](#user-profile-object) object | The account-wide profile customisation || guild_member?<sup>1</sup> | [guild member](/http-api/guild-members/#guild-member-object) object | The membership the target account holds in the named guild || guild_member_profile?<sup>1</sup> | [guild member profile](#guild-member-profile-object) object | The per-guild profile customisation of the target account |-| premium_type?<sup>2</sup> | integer | The [premium type](#premium-types) visible to the caller |-| premium_since?<sup>2</sup> | ISO8601 timestamp | The premium activation time visible to the caller |-| premium_lifetime_sequence?<sup>2</sup> | integer | The lifetime premium sequence visible to the caller |+| premium_type?<sup>2</sup> <sup>7</sup> | integer | The [premium type](#premium-types) visible to the caller |+| premium_since?<sup>2</sup> <sup>7</sup> | ISO8601 timestamp | The premium activation time visible to the caller |+| premium_lifetime_sequence?<sup>2</sup> <sup>7</sup> | integer | The lifetime premium sequence visible to the caller |+| profile_badges | array[[profile badge](#profile-badge-object) object] | The badges to show on the profile, in display order || mutual_friends?<sup>3</sup> | array[[partial user](#partial-user-object) object] | The mutual friends in descending account identifier order || mutual_guilds?<sup>3</sup> | array[[mutual guild](#mutual-guild-object) object] | The guilds the caller and the target are both members of || connected_accounts<sup>4</sup> | array[[connection](/http-api/connections/#connection-object) object] | The verified connections the caller is permitted to see |@@ -562,8 +599,56 @@ The profile read returned by [Get user profile](#get-user-profile) for one targe<sup>6</sup> The field is present only on a restricted read+<sup>7</sup> Deprecated for badge display. Render `profile_badges` instead, which applies the same privacy rules and adds localised labels+A lifetime target that masks its badge reports `premium_type` of `1`, not `2`.+## Profile badge object++One badge on a [full user profile](#full-user-profile-object). The server decides which badges apply, their order, and their text, so a client renders the list as it comes.++### Structure++| Field | Type | Description |+| --- | --- | --- |+| kind<sup>1</sup> | string | A stable key for the badge |+| label | string | The full badge description in the caller's locale, for the tooltip, and the alt text when there is no caption |+| asset<sup>2</sup> | ?string | The 16-character hex hash of the badge image, or null for a text badge |+| aspect_ratio<sup>3</sup> | ?number | The image width divided by its height, or null for a square badge |+| caption<sup>4</sup> | ?string | The short text the badge stands for, or null |+| href | ?string | The absolute URL a click opens, or null |+| small_asset? | string | The image hash for 20 pixels and smaller, served like `asset`. Use it instead of `asset` at those sizes |+| count? | ?integer | Never present on a self-hosted instance |+| accessible_label? | ?string | The label for screen readers, used in place of `label` |+| details?<sup>5</sup> | ?[badge details](#badge-details-object) object | The content of the richer vertical tooltip |++<sup>1</sup> The known values are `staff` and `premium`, which appears only while premium tiers are active on the instance. New values can appear at any time, so a client renders an unknown kind from the other fields++<sup>2</sup> The image is served at `{static_cdn}/badges/{asset}.webp`, where `static_cdn` is the `endpoints.static_cdn` value from [instance discovery](/http-api/instance/). Square badges are 128 by 128 pixels and also have a PNG at `{static_cdn}/badges/{asset}.png`. A hashed file never changes, so it can be cached forever++<sup>3</sup> Render the image at the badge height and `aspect_ratio` times that height wide++<sup>4</sup> A badge with a null `asset` shows its caption as text instead++<sup>5</sup> When present, show a vertical tooltip with the badge art larger at the top, then `title`, then each line. Otherwise `label` is the whole tooltip++### Badge details object++| Field | Type | Description |+| --- | --- | --- |+| title | string | The first line under the badge art |+| lines | array[string] | The further lines, in order |++### Visibility++| Condition | Effect |+| --- | --- |+| The target is hidden or under enforcement | The list is empty |+| The profile is restricted for the caller | Only `staff` remains |+| The target hides the premium badge | `premium` is dropped |+| The target hides the premium activation time | The premium label has no date |+| The target hides its staff flag | `staff` is dropped |+## Get user<RouteHeader method="GET" path="/v1/users/{user_id}" bot />@@ -622,7 +707,7 @@ Returns a [full user profile](#full-user-profile-object) object for one target a<sup>2</sup> The value is trimmed and read as true only for the exact strings `true`, `True`, and `1`. Every other value, including absence, is false:::note[Profile privacy is a field filter]-A read that passes the access check can still be restricted. A restricted read nulls `bio` and `pronouns` in both profile objects, empties `connected_accounts`, nulls `timezone_offset`, and sets `profile_limited` to true. It also removes the premium fields from the body.+A read that passes the access check can still be restricted. A restricted read nulls `bio` and `pronouns` in both profile objects, empties `connected_accounts`, nulls `timezone_offset`, and sets `profile_limited` to true. It also removes the premium fields from the body and keeps only the staff, partner, and bug hunter entries in `profile_badges`.:::### Responsediff --git a/fluxer_docs/src/content/docs/http-api/users/current-user.mdx b/fluxer_docs/src/content/docs/http-api/users/current-user.mdxindex 479dde22f..ba1a48d59 100644--- a/fluxer_docs/src/content/docs/http-api/users/current-user.mdx+++ b/fluxer_docs/src/content/docs/http-api/users/current-user.mdx@@ -16,13 +16,55 @@ Security-sensitive fields and destructive lifecycle operations on this page requ| Account state | Accepted proof || --- | --- |-| No TOTP secret and no registered WebAuthn credential | The current `password` |+| No TOTP secret and no registered WebAuthn credential | The current `password`, or an emailed code when the account has a confirmed email address || A TOTP secret or a registered WebAuthn credential | `mfa_method` of `totp` with `mfa_code`, or `mfa_method` of `webauthn` with `webauthn_response` and `webauthn_challenge` || A registered WebAuthn credential and no TOTP secret | `mfa_method` of `webauthn` as above, or `mfa_method` of `totp` with `mfa_code` holding an unconsumed backup code |-| No password credential and neither of those | None, the requirement is already satisfied |+| No password, no confirmed email address and neither of those | None, the requirement is already satisfied |Once an account holds a TOTP secret or a registered WebAuthn credential, its `password` stops working here. A passkey counts whether or not the account enabled passkeys as a second factor. The `methods` object on a 403 `SUDO_MODE_REQUIRED` reports `backup_codes` so a client knows whether the code input is worth offering.+## Guild entry object++The community an account entered after signing up with an invite.++### Structure++| Field | Type | Description |+| --- | --- | --- |+| guild_id | snowflake | The guild the account entered |+| mode | string | `member` when the account joined, `visit` when it looks around without joining |++## Date of birth result object++### Structure++| Field | Type | Description |+| --- | --- | --- |+| user | [user](/http-api/users/#user-object) object | The updated account |+| entry | ?[guild entry](#guild-entry-object) object | The community to open next, or null |++## Email code delivery object++### Structure++| Field | Type | Description |+| --- | --- | --- |+| code_expires_at | ISO8601 timestamp | When the emailed code stops working, 10 minutes after sending |+| resend_available_at | ISO8601 timestamp | When another code can be requested, 30 seconds after sending |++## Claim result object++### Structure++| Field | Type | Description |+| --- | --- | --- |+| next_step | string | `confirm_email` when the emailed code still has to be entered, `none` when the account is already set up |+| user | [user](/http-api/users/#user-object) object | The updated account |+| code_expires_at?<sup>1</sup> | ISO8601 timestamp | When the emailed code stops working |+| resend_available_at?<sup>1</sup> | ISO8601 timestamp | When another code can be requested |++<sup>1</sup> Present only when `next_step` is `confirm_email`+## Get current user<RouteHeader method="GET" path="/v1/users/@me" bot oauth2="identify" />@@ -83,10 +125,12 @@ Modifies the current account and returns the resulting [user](/http-api/users/#u| has_unread_gift_inventory?<sup>13</sup> | boolean | Whether the gift inventory still holds unread items || mention_flags? | integer | [Reply mention preference](/http-api/users/#reply-mention-preferences), one of `0`, `1`, or `2` || email_token?<sup>14</sup> | string | Email token (1-256 characters) issued by [verify new email](/http-api/users/email-and-password/#verify-new-email) |-| mfa_method? | string | [Sudo verification](/http-api/users/mfa/#sudo-mode) method, either `totp` or `webauthn` |+| mfa_method? | string | [Sudo verification](/http-api/users/mfa/#sudo-mode) method, one of `totp`, `webauthn` or `email_code` || mfa_code? | string | [Sudo verification](/http-api/users/mfa/#sudo-mode) authenticator or backup code (1-32 characters) || webauthn_response? | [WebAuthn assertion](/http-api/users/mfa/#webauthn-assertion-object) object | [Sudo verification](/http-api/users/mfa/#sudo-mode) WebAuthn assertion || webauthn_challenge? | string | [Sudo verification](/http-api/users/mfa/#sudo-mode) WebAuthn challenge (1-256 characters) |+| email_code_ticket? | string | The ticket from [send a sudo email code](/http-api/users/mfa/#send-a-sudo-email-code) (1-128 characters) |+| email_code? | string | The 6-digit code from that email |<sup>1</sup> The value cannot be `everyone` or `here` and cannot contain `fluxer` or `system message`, on every instance including a self-hosted one. On an instance with the `none` tag style, a username another account holds in any letter case returns `USERNAME_ALREADY_TAKEN`@@ -124,6 +168,8 @@ A body that has no `email_token` and nothing beyond `mfa_method`, `mfa_code`, `wA claimed account needs a verified email before changing the username, discriminator, display name, avatar, banner, biography, pronouns, accent colour, timezone, timezone privacy, or any premium badge field. A request without one returns 403 [`PROFILE_EMAIL_VERIFICATION_REQUIRED`](/http-api/errors/).+While the instance [enforces single sign-on](/authentication/#single-sign-on-enforcement), an account linked to the provider that sets `new_password` or `email_token` gets 403 [`SSO_REQUIRED`](/http-api/errors/) and nothing changes.+A [limited account](/http-api/users/#account-limitation) cannot change any of those fields. A request that sets one returns 403 [`ACCOUNT_LIMITED`](/http-api/errors/).An account is unclaimed while it holds no password credential, is not a bot, and does not have the SSO trait. Such an account may set only `new_password`, `has_dismissed_premium_onboarding`, and `has_unread_gift_inventory`. Any other field is rejected with [`UNCLAIMED_ACCOUNTS_CAN_ONLY_SET_EMAIL_VIA_TOKEN`](/http-api/errors/) on the path of the first offending field. The allow-list covers the profile payload only, so `email_token` and the sudo fields stay available as the way such an account claims itself. On an instance where members sign in with a username, a body with `new_password` may also set `username`, which claims the account in one request.@@ -168,6 +214,7 @@ Supplying `new_password` on a claimed account deletes every other authentication| 400 | [error response](/http-api/#error-response) | Body, image, tag, password, entitlement, secondary control, or sudo proof is invalid || 403 | [error response](/http-api/#error-response) | Email verification, sudo verification, or a staff-only field is required, or content is blocked || 403 | [error response](/http-api/#error-response) | The account is limited and the body changes a profile field, and the request returns `ACCOUNT_LIMITED` |+| 403 | [error response](/http-api/#error-response) | Single sign-on is enforced and an account linked to it sets a password or email, returning `SSO_REQUIRED` |### Side effects@@ -177,6 +224,129 @@ A successful change emits [User Update](/gateway/events/#user-update) to the acc20 requests per minute for each authenticated user, on the `user:update` bucket, which is shared with [Accept current policies](#accept-current-policies) and [Reset current premium state](#reset-current-premium-state).+## Set date of birth++<RouteHeader method="PUT" path="/v1/users/@me/date-of-birth" />++Sets the date of birth of an account that has none. Returns a [date of birth result](#date-of-birth-result-object) object.++An instance that does not [collect date of birth](/http-api/instance/#public-registration-fields-object) returns 404 `NOT_FOUND`. An account that already has one returns 409 `DATE_OF_BIRTH_ALREADY_SET`, because a date of birth cannot be changed once set.++### JSON body++| Field | Type | Description |+| --- | --- | --- |+| date_of_birth<sup>1</sup> | string | The date of birth in exact `YYYY-MM-DD` form |++<sup>1</sup> A date that does not exist, is today or later, or lies more than 120 years before today (UTC) returns the field code `INVALID_DATE_OF_BIRTH_FORMAT`++Fluxer resolves the region from the client IP address, with the same minimum age as [register an account](/http-api/authentication/#register-an-account). An age below it returns 403 `ACCOUNT_BELOW_MINIMUM_AGE`. The account is then closed at once, its sessions end, its username is released, and it is deleted after 72 hours. Signing in does not cancel that deletion.++### Response++| Status | Body | Condition |+| --- | --- | --- |+| 200 | [date of birth result](#date-of-birth-result-object) object | The date of birth was set |+| 400 | [error response](/http-api/#error-response) | The date is invalid |+| 403 | [error response](/http-api/#error-response) | The person is below the minimum age |+| 404 | [error response](/http-api/#error-response) | The instance does not collect dates of birth |+| 409 | [error response](/http-api/#error-response) | The account already has a date of birth |++### Side effects++The account leaves the [date of birth step](/http-api/users/#user-object). Settings still on their defaults change to the adult defaults when the person is an adult, with [User Settings Update](/gateway/events/#user-settings-update). Fluxer emits [User Update](/gateway/events/#user-update), adds the account's guilds to its Gateway sessions, and accepts the invite held from sign-up.++### Rate limit++5 requests per hour for each authenticated user, on the `user:date_of_birth` bucket.++## Claim an account++<RouteHeader method="POST" path="/v1/users/@me/claim" />++Adds an email address, and optionally a password, to an unclaimed account, so it can be signed in to from another device. Returns a [claim result](#claim-result-object) object.++An account that is not unclaimed returns 400 `ACCOUNT_ALREADY_CLAIMED`.++### JSON body++| Field | Type | Description |+| --- | --- | --- |+| email?<sup>1</sup> | string | The email address to add |+| password?<sup>2</sup> | string | The password to set (8-256 characters) |++<sup>1</sup> Required on an `email` instance, where a missing value returns the field code `EMAIL_IS_REQUIRED`. Ignored on a `username` instance. The address gets the checks of [register an account](/http-api/authentication/#register-an-account)++<sup>2</sup> Required on a `username` instance, on an instance that sends no email and on an instance whose `verification_basis` is `local_credential`, unless the account has a passkey. A missing value there returns 400 `PASSWORD_REQUIRED_TO_CLAIM`. A breached password returns the field code `PASSWORD_IS_TOO_COMMON`++An address stored on another account, confirmed or not, returns the field code `EMAIL_ALREADY_IN_USE`. On an instance that sends email, the address is stored on the account at once and waits for [confirm the email address](#confirm-the-email-address).++On an instance that sends no email, the address is confirmed at once. The claim result then has `next_step` set to `none` and no timestamps. On a `username` instance `next_step` is always `none`.++### Response++| Status | Body | Condition |+| --- | --- | --- |+| 200 | [claim result](#claim-result-object) object | The account was claimed, or the address waits for its code |+| 400 | [error response](/http-api/#error-response) | The body, address or password is invalid, the address is in use, or the account is already claimed |+| 429 | [rate limit response](/topics/rate-limits/#rate-limit-response-object) | A route, global, address or IP bucket denies the request, or codes to the address are waiting longer |++### Side effects++Fluxer emits [User Update](/gateway/events/#user-update) to the account and emails the code.++### Rate limit++5 requests per hour for each authenticated user, on the `user:claim` bucket.++## Send an email confirmation code++<RouteHeader method="POST" path="/v1/users/@me/email-verification/send" />++Emails a 6-digit code to the unconfirmed address of the account. Returns an [email code delivery](#email-code-delivery-object) object.++An unclaimed account returns 400 `USE_CLAIM_ROUTE`, and an account whose address is already confirmed returns 400 `ACCOUNT_ALREADY_CLAIMED`.++### Response++| Status | Body | Condition |+| --- | --- | --- |+| 200 | [email code delivery](#email-code-delivery-object) object | The code was sent |+| 400 | [error response](/http-api/#error-response) | The account has no unconfirmed address |+| 429 | [rate limit response](/topics/rate-limits/#rate-limit-response-object) | A route, global, address or IP bucket denies the request, or codes to the address are waiting longer |++### Rate limit++3 requests per 15 minutes for each authenticated user, on the `user:email_verification` bucket.++## Confirm the email address++<RouteHeader method="POST" path="/v1/users/@me/email-verification/confirm" />++Confirms the address of the account with the emailed code. Returns the updated [user](/http-api/users/#user-object) object.++### JSON body++| Field | Type | Description |+| --- | --- | --- |+| code | string | The 6-digit code from the email |++### Response++| Status | Body | Condition |+| --- | --- | --- |+| 200 | [user](/http-api/users/#user-object) object | The address was confirmed |+| 400 | [error response](/http-api/#error-response) | The code is wrong or expired |+| 429 | [rate limit response](/topics/rate-limits/#rate-limit-response-object) | Route or global bucket denies the request |++### Side effects++Fluxer emits [User Update](/gateway/events/#user-update) to the account.++### Rate limit++10 requests per minute for each authenticated user, on the `user:email_verification:confirm` bucket.+## Forget authorised IPs<RouteHeader method="DELETE" path="/v1/users/@me/authorized-ips" mfa />@@ -274,7 +444,7 @@ Fluxer marks the account for deletion at the configured deadline and queues it f<RouteHeader method="POST" path="/v1/users/@me/terms-acceptance" />-Records acceptance of the current terms of service and privacy policy. Returns the updated [user](/http-api/users/#user-object) object.+Records acceptance of the current terms of service, and that the current privacy policy was shown. Returns the updated [user](/http-api/users/#user-object) object.### JSON body@@ -284,7 +454,7 @@ The body is an empty object, and an absent or empty body is read as one. Any sup| Status | Body | Condition || --- | --- | --- |-| 200 | [user](/http-api/users/#user-object) object | Policy acceptance was recorded |+| 200 | [user](/http-api/users/#user-object) object | The acceptance was recorded || 400 | [error response](/http-api/#error-response) | The body is not valid JSON, or it parses as JSON that is not an object |### Side effects@@ -295,6 +465,39 @@ Fluxer sets both `terms_agreed_at` and `privacy_agreed_at` to the request time a20 requests per minute for each authenticated user, on the `user:update` bucket, which is shared with [Modify current user](#modify-current-user) and [Reset current premium state](#reset-current-premium-state).+## Preview profile badges++<RouteHeader method="POST" path="/v1/users/@me/profile-badges/preview" />++Returns the current account's [profile badges](/http-api/users/#profile-badge-object) as other people would see them with the given badge settings applied. Nothing is saved.++### JSON body++| Field | Type | Description |+| --- | --- | --- |+| premium_badge_hidden? | boolean | Preview with the premium badge hidden |+| premium_badge_masked? | boolean | Preview with the premium badge masked |+| premium_badge_timestamp_hidden? | boolean | Preview with the premium badge date hidden |+| premium_badge_sequence_hidden? | boolean | Preview with the lifetime sequence hidden |++Each field has the meaning it has on [Modify current user](#modify-current-user). A field that is left out keeps the value the account has saved.++### Response body++| Field | Type | Description |+| --- | --- | --- |+| profile_badges | array[[profile badge](/http-api/users/#profile-badge-object) object] | The badges in display order, localised for the current account |++### Response++| Status | Body | Condition |+| --- | --- | --- |+| 200 | response body | Badges were returned |++### Rate limit++100 requests per 10 seconds for each authenticated user, on the `user:profile::target_id` bucket.+## Reset current premium state<RouteHeader method="POST" path="/v1/users/@me/premium/reset" />