# Accounts

Account management and authentication endpoints. Handles user registration, login flows (email/phone), profile management, and account lifecycle operations. Supports multi-step signup with email/SMS verification, CAPTCHA, and optional admin approval.

## Signup - Step 4: Submit signup reason

 - [POST /api/v1/accounts/add-reason](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1add-reason/post.md): Step 4 of signup (if required): collects reason for joining the platform. Used for manual approval workflows. Notifies admins of pending registration. Required when registration mode is set to approval-based.

## Email/username authentication

 - [POST /api/v1/accounts/authenticate/email](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1authenticate~1email/post.md): Authenticates using email address or username with password. Returns a session token for authenticated requests. The system automatically detects whether the login field is an email (contains @) or username. Updates last sign-in timestamp on successful authentication.

## Phone number authentication

 - [POST /api/v1/accounts/authenticate/phone](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1authenticate~1phone/post.md): Two-step phone authentication process. First call sends SMS code to the phone number. Second call with the code completes authentication and returns session token. Phone number must be registered to an existing account.

## Change user display name

 - [PUT /api/v1/accounts/change/name](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1change~1name/put.md): Updates the display name for a specific user in the account. Can only change names for users belonging to the authenticated account. Specify user by either username or user ID. Changes are immediately reflected and streamed to connected clients.

## Verify CAPTCHA challenge

 - [POST /api/v1/accounts/check-captcha](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1check-captcha/post.md): Step 3 of signup (if enabled): validates CAPTCHA to prevent automated signups. Uses IP address for additional validation. Advances to next step on success. Skip if CAPTCHA is disabled in config.

## Signup - Step 2: Verify email with code

 - [POST /api/v1/accounts/confirm-email](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1confirm-email/post.md): Step 2 of email signup: validates the confirmation code sent to email. Advances registration to next step (CAPTCHA, reason, or account creation). Code expires after a set time and has limited retry attempts.

## Signup - Step 2: Verify phone with code

 - [POST /api/v1/accounts/confirm-phone](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1confirm-phone/post.md): Step 2 of phone signup: validates the SMS code sent to phone number. Advances registration to next step (CAPTCHA, reason, or account creation). Code expires after a set time and has limited retry attempts.

## Delete current account

 - [DELETE /api/v1/accounts/delete](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1delete/delete.md): Permanently deletes the authenticated account and all associated users. Sends deletion notifications to federated followers. Cannot delete if it's the last admin account on the server. This operation is irreversible - all data including posts, follows, and media will be removed.

## Signup - Final Step: Complete account creation

 - [POST /api/v1/accounts/finish-creating](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1finish-creating/post.md): Final step of signup: creates the account and user after all validations pass. Returns account details with authentication token for immediate login. Sends welcome email if applicable. Can optionally update username at this stage.

## Retrieve token for approved phone account

 - [PUT /api/v1/accounts/get-token/{hash}](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1get-token~1%7Bhash%7D/put.md): One-time token retrieval for phone-based accounts approved by admin. Used when admin manually approves a phone registration. The signup request is deleted after successful token generation. Only works for accounts in USER step of registration.

## Get current account profile

 - [GET /api/v1/accounts/profile](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1profile/get.md): Returns the authenticated account with all associated users. Most accounts have a single user, but the system supports multiple users per account. Requires authentication token.

## Resend verification code

 - [PUT /api/v1/accounts/resend-code/{hash}](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1resend-code~1%7Bhash%7D/put.md): Resends verification code via email or SMS based on registration type. Automatically detects whether to send email or SMS from the signup request. Rate limited to prevent abuse. Use when code was not received or expired.

## Resend confirmation email

 - [PUT /api/v1/accounts/resend-email/{hash}](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1resend-email~1%7Bhash%7D/put.md): Resends the email verification code for pending registrations. Use when the initial email was not received or code expired. Rate limited to prevent abuse. Deprecated - use /resend-code instead.

## Signup - Step 1: Start email signup process

 - [POST /api/v1/accounts/signup](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1signup/post.md): Initiates account registration with email verification. Step 1 of multi-step signup: validates input, checks availability, sends confirmation email. Returns registration hash for tracking signup progress. Username must not be reserved, email must be unique and not blocked.

## Signup - Step 1: Start phone signup process

 - [POST /api/v1/accounts/signup-phone](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1signup-phone/post.md): Initiates account registration with phone verification. Step 1 of multi-step signup: validates input, checks availability, sends SMS code. Returns registration hash for tracking signup progress. Username must not be reserved, phone number must be unique.

## Switch between account users

 - [POST /api/v1/accounts/user/reselect-user](https://docs.wellesley.social/openapi/accounts/paths/~1api~1v1~1accounts~1user~1reselect-user/post.md): Generates a new token for a different user within the same account. Useful for accounts with multiple users to switch active user context. Either userId or userName must be provided. Only users belonging to the authenticated account can be selected.