# Password and email address

## Summary

A person can replace a forgotten password from a link emailed to them, change
their password while signed in, and move their account to a new email address.
The new address takes effect only after it is confirmed from its own inbox.

Each of these changes says what it does to the account's sessions, emailed
links, API keys and connected apps. A new password always ends other sessions
and revokes every API key and connected app. A new email address ends nothing.

This page also covers the name on the account and where the account's
settings are.

## Who can do what

Organization roles (owner, admin, member) play no part here. A verified and an
unverified account can do the same things on this page.

| Action | Signed-out visitor | Signed-in person | API key or connected app |
| --- | --- | --- | --- |
| Ask for a password reset link | Yes, for any address. The answer never says whether the address has an account | Yes | Public operation; no scope exists |
| Set a new password from a reset link | Yes: whoever holds the link | Yes | Public operation |
| Change the password | No | Yes, with the current password | No: `FORBIDDEN`, reason `SESSION_REQUIRED` |
| Start an email change | No | Yes, with the current password | No: `SESSION_REQUIRED` |
| Cancel a pending email change | No | Yes | No: `SESSION_REQUIRED` |
| Confirm an email change from the emailed link | Yes: whoever holds the link | Yes | Public operation |
| Change the name | No | Yes | No: `SESSION_REQUIRED` |

Nobody can change another person's password, email address or name. No role
grants that.

No operation on this page is an MCP tool.

## How it works

### What each change does

| Change | Sessions | Other emailed links of the account | API keys and connected apps | A pending email change | Email verified? | Signed in afterwards? |
| --- | --- | --- | --- | --- | --- | --- |
| New password from a reset link | All end | All become invalid | All revoked | Cancelled | Becomes verified | No. Sign in with the new password |
| Password changed while signed in | All others end; the current one stays | All become invalid | All revoked | Cancelled | Unchanged | Yes, in the current browser |
| New password chosen from a verification link in another browser | All end | All become invalid | All revoked | Cancelled | Becomes verified | No |
| Email change confirmed | None end | All become invalid | None revoked | Completed | The new address is verified | Unchanged |
| Email change cancelled | None end | Only the confirmation link becomes invalid | None revoked | Cancelled | Unchanged | Unchanged |
| Name changed | None end | Unchanged | None revoked | Unchanged | Unchanged | Unchanged |

- "Emailed links of the account" are its verification link, its password reset
  link and its email change confirmation link. Invitation links are separate
  and are not affected by any change on this page.
- "All revoked" means every API key and connected app of the person, in every
  organization. They stop working at once and cannot be revived. The person
  creates new keys and connects apps again
  ([Credentials and scopes](../agents/credentials.md)).
- The third row is described in
  [Sign-up and email verification](sign-up.md#verifying-the-email-address).

### Forgotten password: asking for a link

- The person enters an email address. Spaces at both ends are removed. The
  address is matched without regard to upper and lower case.
- The answer is always the same: `202`, and in the app "Check your email". It
  never says whether the address has an account.
- If the address has an account, verified or not, a reset email goes to it. Its
  subject is "Reset your Talewright password" and its button is "Reset
  password". It says "For security, this link expires in 1 hour."
- If the address has no account, or the account was deleted, nothing is sent.
- The emailed link is the only way to replace a forgotten password.
- Asking changes nothing else. The current password keeps working and every
  session stays, until a new password is actually set.
- A reset link works once and for 1 hour.
- Only the newest link works. Asking again makes the earlier link invalid.
- Requests are limited to 10 per email address and 100 per client address in
  15 minutes.
- The form sends one request at a time, so a double click sends one email.

### Forgotten password: setting the new password

- The link opens a page that asks for a new password of 12 to 128 characters.
  Every character counts and nothing is trimmed.
- The link works in any browser, on any device. It needs no session.
- The new password is not compared with the old one.
- Setting it does everything in the first row of the table above:
  - the password is replaced;
  - an unverified email becomes verified, because the link reached the inbox;
  - every session ends, including one in the browser that sets the password;
  - every other emailed link of the account becomes invalid;
  - a pending email change is cancelled;
  - every API key and connected app of the person is revoked;
  - the count of failed sign-in attempts for the email address from all
    client addresses is cleared, and so is the sign-in count for it from
    the client address that set the password;
  - the email "Your Talewright password was changed" goes to the account's
    address.
- It does not sign in. The person signs in with the new password.
- A too-short or too-long password is refused and does not use the link up.
- An unknown, expired, used or replaced link gets `400 TOKEN_INVALID`, "This
  link is invalid or has expired". The answer never says which.
- Attempts to set a password from a link are limited to 100 per client address
  in 15 minutes.

### Changing the password while signed in

- The person enters the current password and a new one.
- The new password must be 12 to 128 characters and must differ from the
  current one.
- The new password is compared with the current one only. No earlier
  passwords are kept, so an older password can be used again.
- A password does not expire. Nothing asks for a new one after a time.
- Checks happen in this order: the new password's length, then the current
  password, then that the two differ.
- A wrong current password gets `422 VALIDATION_FAILED` on `currentPassword`,
  "current password is incorrect". It does not sign the person out.
- A successful change does everything in the second row of the table above.
  The browser that made the change stays signed in. Every other browser is
  signed out.
- The email "Your Talewright password was changed" goes to the account's
  address.
- Changing the password does not verify an unverified email.

### Limit on wrong current passwords

- Changing the password, starting an email change and deleting the account
  each ask for the current password. They share one count per account.
- 10 attempts are checked in 15 minutes. Further attempts are refused with
  `429 RATE_LIMITED`, even with the correct password, until the 15 minutes
  end.
- A correct password clears the count.
- The count belongs to the account, not to the browser or the network.

### Changing the email address

- The person enters the new address and the current password. Without the
  current password the address cannot be changed.
- An account has one email address. There is no second or backup address.
- The new address follows the same rules as at sign-up: spaces at both ends
  removed, exactly one `@` with text on both sides, no spaces or control
  characters, at most 320 characters.
- It must differ from the current address. Upper and lower case do not count as
  a difference.
- Checks happen in this order: the new address's shape, then the current
  password, then the limit on requests, then that the address differs.
- An account can ask for an email change 10 times in 15 minutes. Further
  requests are refused with `429 RATE_LIMITED` until the 15 minutes end, and
  send no email. A request with a wrong current password is not counted here;
  it counts toward the limit on wrong current passwords.
- A successful request answers `202` and sends two emails:
  - to the new address, "Confirm your new email for Talewright" with the button
    "Confirm new email" and "For security, this link expires in 24 hours.";
  - to the current address, "Your Talewright email is being changed", which
    names the new address.
- Nothing changes yet. The account keeps its current address, the person keeps
  signing in with it, and the account shows the new address as pending.
- A confirmation link works once and for 24 hours.
- A new request replaces the pending one. The earlier confirmation link
  becomes invalid.
- A pending change ends when it is confirmed, cancelled, replaced, 24 hours
  old, or when the password is changed or reset.
- An unverified account can change its email. Confirming the new address
  verifies the account.

### When the new address belongs to another account

- The person who asks sees the same answer and the same pending change as for
  a free address. The request does not reveal that the address is taken.
- No confirmation link is sent, so the change can never be confirmed.
- The holder of the address gets "Someone tried to use your email on
  Talewright", which says that nothing changed. They get it at most once in 15
  minutes.
- The notice to the requester's current address is sent as usual.
- The pending change stays visible until it is cancelled, replaced or 24 hours
  old.

### Confirming the new address

- Opening the confirmation link moves the account to the new address.
- It needs no session. The link works in any browser, on any device, signed in
  or not. Whoever opens it confirms the change.
- Confirming:
  - sets the account's email to the new address;
  - marks the address as verified;
  - makes every other emailed link of the account invalid;
  - keeps every session, API key and connected app;
  - keeps the password.
- From then on only the new address signs in. The old address is free: anyone
  can create a new account with it.
- No email is sent at confirmation. The notice sent to the old address when
  the change was requested is the only message it gets.
- If another account took the address between the request and the
  confirmation, confirming answers `409 CONFLICT`, "another account uses this
  email address". The account keeps its email. The link is not used up.
- Attempts to confirm are limited to 100 per client address in 15 minutes.

### Cancelling a pending change

- The person who started the change can cancel it while it is pending.
- The confirmation link stops working at once.
- Cancelling when nothing is pending is not an error.
- Cancelling needs no password.

### The name

- The name is 1 to 200 characters after spaces at both ends are removed, with
  no control characters.
- Changing it needs no password.
- The name appears on file versions and to the people in the person's
  organizations. A changed name shows everywhere the old one did, including on
  versions uploaded earlier.
- Emails greet the person by this name: "Hi {full name},". Words in braces,
  here and below, stand for the real value.
- An account has no profile photo and no username. The name and the email
  address are all it shows of a person.

### Emails this feature sends

| Email | Subject | Sent to | When |
| --- | --- | --- | --- |
| Password reset | "Reset your Talewright password" | The account's address | A reset is requested for an address with an account |
| Password changed | "Your Talewright password was changed" | The account's address | A password is set from a reset link, or changed while signed in |
| Email change confirmation | "Confirm your new email for Talewright" | The new address | An email change is requested and the new address is free |
| Email change notice | "Your Talewright email is being changed" | The current address | An email change is requested |
| Email change attempt | "Someone tried to use your email on Talewright" | The holder of the requested address | An email change is requested to an address that has an account; at most once per holder in 15 minutes |

- Under their buttons, the password reset email and the email change
  confirmation also print the full link, after "If the button does not work,
  copy and paste this link into your browser:".
- The password-changed email says "The password for your Talewright account
  was just changed." and "If this was not you, reset your password now to
  secure your account:" with the button "Reset password".
- The email change notice says "Someone signed in to your Talewright account
  asked to change its email address to {new address}. The change takes effect
  once the new address is confirmed." It has the same "Reset password" button.
- Both end with "This security notice was sent to {address} and cannot be
  turned off."
- The email change attempt says "Someone tried to move another Talewright
  account to this email address. It already belongs to your account, so
  nothing changed." and "You do not need to do anything."
- No password-changed email is sent when a password is chosen from a
  verification link.

## In the app

### Where the account's settings are

- Open the account menu at the bottom of the navigation and choose "Settings",
  or choose "Open settings" in the command palette.
- Settings opens on "Account".
- The settings navigation has a group "Account" with, among others:
  - "Account": the name;
  - "Security": the password and the email address;
  - "Sessions", under "Security"
    ([Sign-in and sessions](sign-in-and-sessions.md#the-sessions-page));
  - "Delete account", under "Security"
    ([Deleting an account](delete-account.md)).
- "Security" is a group that opens and closes. Opening "Security" shows
  "Sessions" and "Delete account" under it, and they stay shown while you
  are on one of the three pages. On any other page the group is closed, and
  the arrow at its end, "Show Security sub-items", opens and closes it
  without leaving that page.
- On a narrow screen the navigation opens from the button that shows the
  current page's title.

### Forgot password

- On the sign-in page choose "Forgot password?". It opens `/forgot-password`.
- Heading: "Reset your password", with "We will email you a link to set a new
  password." Field: "Email". Button: "Send reset link". Below: "Remembered it?
  Sign in".
- After sending: "Check your email" with "If {address} belongs to an account,
  we sent it a link to set a new password. The link expires in 1 hour." and
  "Use a different email".
- Problems: "Enter a valid email address.", "Too many attempts. Try again in 4
  minutes." (the time varies) and "Something went wrong. Try again."
- "Enter a valid email address." shows under "Email" for an empty address,
  for one longer than 320 characters and for one that holds a control
  character.

### Setting the new password

- The emailed link opens `/reset-password`. The page removes the token from
  the address bar and the browser history.
- Heading: "Set a new password", with "Setting a new password signs you out
  everywhere." Field: "New password", with "At least 12 characters." Button:
  "Set password".
- Problems under the field: "Use at least 12 characters." and "Use 128
  characters or fewer."
- After setting it, the sign-in page opens with "Password updated" and "Sign in
  with your new password." The email field starts filled with the address the
  reset was requested for, when that was done in the same browser. A browser
  signed in to a different account opens the app instead, with the message
  "Password updated".
- A dead link is found when "Set password" is pressed, not when the page
  opens. The page then shows "Link expired or invalid" with "Reset links work
  once and expire after 1 hour. Request a new one to set your password.", the
  button "Request a new link" and "Back to sign in".
- The page opened without a link shows the same.

### Changing the password

- Open Settings, then "Security" (`/settings/security`). The section
  "Password" says "Changing your password signs out every other session and
  revokes your API keys and connected apps."
- Fields: "Current password" and "New password", with "At least 12
  characters." Button: "Change password".
- Each password field has a button at its end that shows what was typed,
  and hides it again. The same holds for the password fields of the reset
  page and of the email section.
- Problems, each under its field:
  - "Your current password is incorrect." The field takes focus.
  - "Use at least 12 characters." or "Use 128 characters or fewer."
  - "Choose a password different from your current one."
- After too many wrong current passwords: "Too many attempts. Try again in 4
  minutes."
- After a change the form is emptied and the message reads "Password changed.
  Your other sessions were signed out and your API keys and connected apps
  revoked."

### Changing the email address

- On the same page, the section "Email" says "You sign in with {address}. A
  new address takes effect once you open the link we send to it."
- Fields: "New email" and "Current password". Button: "Change email".
- Problems, each under its field: "Enter a valid email address.", "This is
  already your email address." and "Your current password is incorrect."
- After too many wrong current passwords or too many requests: "Too many
  attempts. Try again in 4 minutes."
- After a request the section shows "Check {new address} for a confirmation
  link. Your email stays {current address} until you open it." with the button
  "Cancel change". This stays after a reload, for as long as the change is
  pending.
- "Cancel change" removes it and shows "Email change cancelled". If that
  fails: "Could not cancel the email change. Try again."

### Confirming the new address

- The emailed link opens `/confirm-email`. The page removes the token from the
  address bar and the browser history, and sends the link once.
- While it works: "Confirming your email" with "One moment while we confirm
  your link."
- Confirmed: "Email confirmed" with "Email updated. Use the new address the
  next time you sign in." and "Continue to Talewright".
- Address taken meanwhile: "Email not changed" with "This address is already
  used by another account. Your email stays as it was. Start a new change from
  your account settings." and "Open security settings".
- Dead link, or the page opened without one: "Link expired or invalid" with
  "Confirmation links work once and expire after 24 hours. Start the change
  again from your account settings." and "Open security settings".
- Anything else: "Could not confirm your email" with "Too many attempts. Try
  again in 4 minutes." or "Something went wrong. Try again.", and "Try again".

### Changing the name

- Open Settings, then "Account" (`/settings/account`). The section "Profile"
  says "Your name appears on versions and to people in your organizations."
- Field: "Full name". Button: "Save", which is disabled until the name
  differs.
- After saving: "Profile updated". The account menu shows the new name.
- Problem: "Enter your name, up to 200 characters."

## For agents

These operations are for people in a browser. None is an MCP tool.

| Operation | Capability ID | Access | MCP |
| --- | --- | --- | --- |
| `POST /v1/auth/password-reset` | `account.password_reset.request` | public | none |
| `POST /v1/auth/password-reset/confirm` | `account.password_reset.confirm` | public | none |
| `POST /v1/me/password` | `account.password.change` | session only | none |
| `POST /v1/me/email` | `account.email.change` | session only | none |
| `DELETE /v1/me/email` | `account.email.cancel` | session only | none |
| `POST /v1/auth/email-change/confirm` | `account.email_change.confirm` | public | none |
| `PATCH /v1/me` | `account.update` | session only | none |

- A session-only operation called with a valid bearer token is refused with
  `403 FORBIDDEN`, `details.reason` `SESSION_REQUIRED`.
- On a session-only operation, a bearer token that does not authenticate
  gets `401 UNAUTHENTICATED`, reason `INVALID_TOKEN`.
- A public operation ignores a bearer token, valid or not. A request with
  both a session cookie and a bearer token gets `401 UNAUTHENTICATED`,
  reason `AMBIGUOUS_CREDENTIALS`.
- A request that changes something and carries a session cookie must send an
  `Origin` header equal to the app's origin.
- **What a password change means for an agent.** When the member it acts for
  changes or resets their password, the agent's API key or connected app is
  revoked. Its next request answers `401 UNAUTHENTICATED`, reason
  `INVALID_TOKEN`, "The bearer token is invalid, expired or revoked". A
  connected app's refresh is refused too. Only the member can issue a new
  credential, in a browser.
- An email change or a name change does not touch credentials.

`POST /v1/auth/password-reset`

- Body: `email`. `202` whenever the address is well formed. No body.
- `422 VALIDATION_FAILED` on `email`, `429 RATE_LIMITED`.

`POST /v1/auth/password-reset/confirm`

- Body: `token` (the `token` query parameter of the emailed link) and
  `newPassword`.
- `204`: password set. No cookie is set.
- `400 TOKEN_INVALID`, `422 VALIDATION_FAILED` on `newPassword` (the link stays
  usable), `429 RATE_LIMITED`.

`POST /v1/me/password`

- Body: `currentPassword`, `newPassword`. `204`: changed.
- `422 VALIDATION_FAILED` on `currentPassword` or `newPassword`,
  `429 RATE_LIMITED`, `401 UNAUTHENTICATED`.

`POST /v1/me/email`

- Body: `newEmail`, `currentPassword`. `202`: accepted. No body.
- `422 VALIDATION_FAILED` on `newEmail` or `currentPassword`,
  `429 RATE_LIMITED`, `401 UNAUTHENTICATED`.
- The pending address is `pendingEmail` in `GET /v1/me`.

`DELETE /v1/me/email`

- `204`: cancelled, or nothing was pending.

`POST /v1/auth/email-change/confirm`

- Body: `token`. `204`: the account has the new address.
- `400 TOKEN_INVALID`, `409 CONFLICT`, `429 RATE_LIMITED`.

`PATCH /v1/me`

- Body: `fullName`. `200` with the user: `id`, `email`, `fullName`.
- `422 VALIDATION_FAILED` on `fullName`, `401 UNAUTHENTICATED`.

Worked example: change the email address, then confirm it with the token from
the email sent to the new address.

```sh
curl -i https://app.usetalewright.com/v1/me/email \
  -b cookies.txt \
  -H 'Origin: https://app.usetalewright.com' \
  -H 'Content-Type: application/json' \
  -d '{"newEmail":"ada@newdomain.example","currentPassword":"correct horse battery"}'
# 202 Accepted

curl https://app.usetalewright.com/v1/me -b cookies.txt
# {"user":{"id":"...","email":"ada@example.com","fullName":"Ada Lovelace"},
#  "emailVerified":true,"pendingEmail":"ada@newdomain.example","workspaces":[...]}

curl -i https://app.usetalewright.com/v1/auth/email-change/confirm \
  -H 'Content-Type: application/json' \
  -d '{"token":"<token from the emailed link>"}'
# 204 No Content
```

A wrong current password:

```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "current password is incorrect",
    "details": { "field": "currentPassword" }
  },
  "requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
```

## Edge cases

Forgotten password

1. **The address has no account.** The page shows the same "Check your email".
   Nothing is sent. Why: the answer must not reveal who has an account.
2. **The address is typed in another case, or with spaces around it.** It
   matches the account.
3. **The account is unverified.** The reset email is sent. Using it sets the
   password and verifies the email.
4. **Two reset emails were requested.** Only the link in the newest works.
5. **The link is more than 1 hour old.** Dead. Request a new one.
6. **The link is used a second time.** Dead. The password set the first time
   stays.
7. **A dead link is opened.** The page still shows the password form. "Link
   expired or invalid" appears after "Set password".
8. **The new password is too short.** Reported under "New password". The link
   is not used up.
9. **A request to the API sends a too-short password with a dead link.** The
   password is reported first (`422`). Why: the fields are checked before the
   link.
10. **The new password is the same as the old one.** Accepted. Everything else
    still happens: sessions end, credentials are revoked.
11. **The browser that sets the password is signed in to the account.** It is
    signed out too and lands on the sign-in page.
12. **The browser that sets the password is signed in to a different
    account.** That account is untouched. After the reset the app opens that
    account's start page with the message "Password updated", because the
    sign-in page is skipped for a signed-in browser.
13. **A reset was requested and never used.** Nothing changed. The old
    password works and the link expires after 1 hour.
14. **The link is opened on another device than the one that asked.** It works.
15. **Someone else asks for a reset of your account.** You get the email. If
    you ignore it, nothing changes. At most 10 can be requested for your
    address in 15 minutes.
16. **The person was limited after too many failed sign-ins.** Setting a new
    password clears the failed attempts, so the new password signs in at once
    from the address that completed the reset.
17. **A verification link was outstanding.** The reset makes it invalid and
    verifies the email itself.
18. **Scripts and agents used the person's API keys.** They stop working the
    moment the new password is set. New keys must be created.
19. **The account was deleted.** No reset email is sent for its old address.

Changing the password

20. **The current password is wrong.** Reported under "Current password". The
    person stays signed in. The attempt counts toward the limit.
21. **The current password is wrong and the new one is too short.** The new
    password is reported first, and the attempt is not counted.
22. **The new password equals the current one.** Refused: "Choose a password
    different from your current one."
23. **Ten wrong current passwords in 15 minutes.** The next attempt is refused
    even with the correct password. The same count blocks starting an email
    change and deleting the account until the window ends.
24. **The person is signed in on a phone and changes the password on a
    laptop.** The laptop stays signed in. The phone is signed out at its next
    request.
25. **An email change was pending.** It is cancelled. Start it again after the
    password change.
26. **The account is unverified.** The password can be changed. The account
    stays unverified.

Changing the email address

27. **The new address equals the current one in another case.** Refused: "This
    is already your email address."
28. **The new address has a typing mistake.** The confirmation went to the
    mistyped address. Choose "Cancel change" at once, or start the change
    again with the right address, which makes the mistyped link invalid. Why
    this matters: whoever opens a confirmation link confirms the change,
    signed in or not.
29. **The new address belongs to another account.** Everything looks as usual,
    but no confirmation email arrives. The holder of the address is told that
    nothing changed. The change stays pending until it is cancelled, replaced
    or 24 hours old.
30. **A second change is requested before the first is confirmed.** The second
    replaces the first. The first link is dead. The current address gets a
    notice for each request.
31. **The confirmation link is opened in a browser that is not signed in.** The
    change is confirmed. The page offers "Continue to Talewright", which leads
    to sign-in.
32. **The confirmation link is opened in a browser signed in to a different
    account.** The account the link belongs to is changed. The signed-in
    account is not.
33. **The confirmation link is opened twice.** The second time: "Link expired
    or invalid". The change stays confirmed.
34. **Another account took the address between request and confirmation.**
    "Email not changed". The account keeps its email. The link is not used up.
35. **The link is more than 24 hours old.** Dead. The pending notice in
    settings is gone. Start again.
36. **The change is cancelled and the link is opened afterwards.** Dead.
37. **The change is confirmed while the person is signed in elsewhere.** Every
    session stays signed in and shows the new address at its next load.
38. **The person tries to sign in with the old address after confirming.**
    `INVALID_CREDENTIALS`. Only the new address signs in.
39. **Someone signs up with the old address after the change.** It creates a
    new, separate account.
40. **An invitation was sent to the old address.** After the change it cannot
    be accepted by this account, because an invitation is for the address it
    was sent to. Ask for a new invitation to the new address.
41. **The account is unverified.** Confirming the new address verifies it. A
    verification link sent earlier to the old address becomes invalid.
42. **The owner of the account did not ask for the change and sees the notice
    at the old address.** Resetting the password from that email's "Reset
    password" button cancels the pending change, ends every session and
    revokes every credential.
43. **The change was confirmed by someone who should not have.** No further
    email goes to the old address at confirmation. The notice sent at the
    request is the only warning.
44. **The current password is wrong.** Reported under "Current password". It
    counts toward the same limit as a password change.
45. **The person asks for an email change an eleventh time in 15 minutes.**
    `429 RATE_LIMITED`. No email is sent and the pending change stays as it
    was. Each request emails an address that did not ask for it, so they are
    limited per account.

The name

46. **The name is only spaces.** Refused: "Enter your name, up to 200
    characters."
47. **The name is unchanged, or differs only by spaces at its ends.** "Save"
    stays disabled.
48. **The name is changed after files were uploaded.** Earlier versions show
    the new name.

Everywhere

49. **Email cannot be sent at the moment.** A request that would send one
    answers `503 UNAVAILABLE` with reason `EMAIL_UNAVAILABLE`, and the change
    it belongs to does not happen.
50. **A button is double-clicked.** Requesting a reset link sends one request.

## Errors

| Code | HTTP | Meaning here | What to do |
| --- | --- | --- | --- |
| `VALIDATION_FAILED` | 422 | `details.field` `newPassword`: "newPassword must be 12 to 128 characters", or "newPassword must differ from the current password". | Choose another password. A reset link stays usable. |
| `VALIDATION_FAILED` | 422 | `details.field` `currentPassword`: "current password is incorrect", or "currentPassword must be 1 to 1024 bytes". | Enter the current password. Use "Forgot password?" if it is lost. |
| `VALIDATION_FAILED` | 422 | `details.field` `newEmail`: "newEmail must be an email address of at most 320 characters", or "newEmail is already the account's email". | Enter a different, well-formed address. |
| `VALIDATION_FAILED` | 422 | `details.field` `email` on a reset request: "email must be 1 to 320 characters" or "email must not contain control characters". | Correct the address. |
| `VALIDATION_FAILED` | 422 | `details.field` `fullName`: "fullName must be 1 to 200 characters" or "fullName must not contain control characters". | Correct the name. |
| `TOKEN_INVALID` | 400 | "This link is invalid or has expired". The reset or confirmation link is unknown, expired, used, replaced or cancelled. | Request a new reset link, or start the email change again. |
| `CONFLICT` | 409 | "another account uses this email address". The address was taken before the change was confirmed. | Start a change to another address. |
| `RATE_LIMITED` | 429 | "Too many attempts; try again later". `details.retryAfterSeconds` and `Retry-After` give the wait. | Wait that long. |
| `UNAUTHENTICATED` | 401 | "Authentication required". No live session. | Sign in again. |
| `UNAUTHENTICATED` | 401 | Reason `INVALID_TOKEN`, for a credential: it was revoked, for example by a password change. | The member creates a new credential. |
| `FORBIDDEN` | 403 | Reason `SESSION_REQUIRED`: a credential called a session-only operation. | Do it in the app. |
| `FORBIDDEN` | 403 | "Forbidden". The `Origin` header is not the app's origin, or a session cookie came without one. | Send requests from the app, or with the app's origin. |
| `UNAVAILABLE` | 503 | Reason `EMAIL_UNAVAILABLE`: email cannot be sent right now. Nothing was changed. | Try again later. |

## Limits

| What | Limit |
| --- | --- |
| New password | 12 to 128 characters |
| Email address | At most 320 characters |
| Full name | 1 to 200 characters after trimming |
| Password reset link lifetime | 1 hour, single use, newest only |
| Email change confirmation link lifetime | 24 hours, single use, newest only |
| Pending email changes per account | 1 |
| Reset requests for one email address | 10 in 15 minutes |
| Reset requests from one client address | 100 in 15 minutes |
| Attempts to set a password from a link, per client address | 100 in 15 minutes |
| Attempts to confirm an email change, per client address | 100 in 15 minutes |
| Current-password checks per account (password change, email change and account deletion together) | 10 in 15 minutes |
| Email change requests per account | 10 in 15 minutes |
| "Someone tried to use your email on Talewright" emails | 1 per holder in 15 minutes |

- A 15-minute window starts at the first attempt. Attempts refused during it
  do not make it longer.
- A request refused because a field is malformed is not counted.

## Questions and answers

**I forgot my password. What do I do?**
On the sign-in page choose "Forgot password?", enter your email address and
open the link in the email. It works for 1 hour.

**I asked for a reset link and no email came.**
The page shows "Check your email" whether or not the address has an account.
Check that you used the address of your account, and look in the spam folder.
Only the newest email's link works.

**Does asking for a reset change anything?**
No. Your password and sessions stay as they are until you set a new password.

**I got a reset email I did not ask for.**
Someone entered your address. Nothing changed. You can ignore the email.

**Does resetting my password sign me out?**
Yes, everywhere, including the browser you reset it in. Then you sign in with
the new password.

**Why did my API keys and connected apps stop working after I changed my
password?**
Every password change or reset revokes them all. Someone who had your password
or a session could have created them. Create new keys and connect the apps
again.

**Can I reuse my old password?**
When changing it while signed in, no: the new one must differ from the current
one. When resetting from an emailed link, the new one is not compared with the
old one.

**I changed my password. Am I still signed in?**
In the browser where you changed it, yes. Everywhere else, no.

**I got "Your Talewright password was changed" and it was not me.**
Use the "Reset password" button in that email at once. Setting a new password
ends every session and revokes every credential.

**How do I change my email address?**
Under Settings, Security, enter the new address and your current password,
then open the link sent to the new address. Until then nothing changes.

**I started an email change but no confirmation arrived.**
Check the address shown in settings. If it has a typing mistake, choose
"Cancel change" and start again. If the address already belongs to another
Talewright account, no confirmation is sent.

**Can I undo an email change?**
Before it is confirmed: "Cancel change". After it is confirmed: start a new
change back to the old address, as long as nobody has taken it.

**Do I have to be signed in to confirm my new address?**
No. The link works in any browser.

**Does changing my email sign me out or revoke my API keys?**
No. Sessions, API keys and connected apps stay.

**What happens to my old address?**
It no longer signs in and is free for a new account.

**I was invited at my old address. Can I still accept?**
No. An invitation is for the address it was sent to. Ask for a new invitation
to your new address.

**I got "Someone tried to use your email on Talewright".**
Someone tried to move their account to your address. It already belongs to
your account, so nothing changed. You do not need to do anything.

**I got "Your Talewright email is being changed" and it was not me.**
Someone signed in to your account asked for it. Use the "Reset password"
button in that email. A reset cancels the pending change and ends every
session.

**Too many wrong passwords. How long am I blocked?**
Until the 15 minutes that began with the first attempt end. The message shows
the time. The block covers password change, email change and account deletion
together.

**Can I change my password or email before verifying my email?**
Yes, both.

**Can an agent change my password, email or name?**
No. These operations refuse API keys and connected apps and are not MCP tools.

**Where do I change my name?**
Settings, Account, "Full name".

## Related pages

- [Sign-up and email verification](sign-up.md)
- [Sign-in and sessions](sign-in-and-sessions.md)
- [Deleting an account](delete-account.md)
- [Invitations](../organizations/invitations.md)
- [Credentials and scopes](../agents/credentials.md)
- [Connected apps](../agents/connected-apps.md)
- [Errors](../reference/errors.md)
- [Limits](../reference/limits.md)
