# Sign-up and email verification

## Summary

An account is one person: a name, an email address and a password. A person
creates it on the sign-up page, or from the link in an invitation email. A new
account is signed in at once and can work at once. Its email address is
unverified until the person opens the link Talewright emails to it.

Verification proves that the person controls the address. Only a few actions
wait for it: deleting a workspace or an organization, and setting file
statuses through an API key or connected app. An account that never verifies
and holds nothing is removed 30 days after sign-up.

Sign-up can be open to everyone or closed. While it is closed, only listed
addresses and people with an invitation create accounts.

## Who can do what

Organization roles (owner, admin, member) play no part here. What matters is
whether the browser is signed in and whether the account's email is verified.

| Action | Signed-out visitor | Signed in, email unverified | Signed in, email verified | API key or connected app |
| --- | --- | --- | --- | --- |
| Create an account | Yes, when sign-up is open, the address is on the allowlist, or the request carries a live invitation to the address | The app sends a signed-in browser on to the app instead of showing the form | Same | Not a use for a credential. The operation is public and ignores a bearer token |
| Verify an email from the emailed link | Yes. Only the browser that signed up is signed in by it; any other browser must choose a new password | Yes. The session stays as it is | Yes. Nothing changes | Public operation; no scope exists |
| Ask for a new verification link | Yes, for any address. The answer never says whether the address has an account | Yes, with "Resend verification email" | Nothing is sent for a verified account | Public operation; no scope exists |
| Sign in, create organizations and workspaces, upload files, invite people, accept invitations, create API keys | - | Yes | Yes | See the page of each feature |
| Delete a workspace or an organization | - | No: `EMAIL_NOT_VERIFIED` | Yes, if the role allows it | Not available to credentials |
| Delete the own account | - | Yes, with the current password, unless the person is the only owner of a live organization | The same | Not available to credentials |
| Set file statuses | - | Yes in the browser, if the role allows it | Yes, if the role allows it | Needs the `files:approve` scope and a member whose email is verified |

No account operation is an MCP tool. No credential scope grants any of them.

## How it works

### Creating an account

- Sign-up takes three values: full name, email address and password.
- **Email address.** Spaces at both ends are removed. The rest must have
  exactly one `@` with text on both sides, no spaces or control characters, and
  at most 320 characters. Nothing else is checked: the domain does not have to
  exist and no test message is sent first.
- Addresses are compared without regard to upper and lower case.
  `Ada@Example.com` and `ada@example.com` are the same account. The address is
  stored and shown as it was typed.
- Nothing else is normalized. `ada+files@example.com` and `ada@example.com` are
  two different addresses.
- **Password.** 12 to 128 characters. Every character counts, spaces included.
  The password is never trimmed. There is no rule about letters, digits or
  symbols.
- **Full name.** 1 to 200 characters after spaces at both ends are removed. No
  control characters. A name made only of spaces is refused.
- **A new address** creates the account at once. The browser is signed in for
  30 days. The account is unverified. A verification email goes to the
  address. The API answers `201`.
- **An address that already has an account** creates nothing and signs nobody
  in. The password and name that were typed are discarded. The existing
  account is not changed. Its holder gets the email "You already have a
  Talewright account", at most once per 15 minutes. The API answers `202`.
- So sign-up tells the person at the keyboard whether an address is taken: a
  new address signs in at once, a taken one does not. The attempt limits bound
  how often anyone can ask.
- Two sign-ups for the same new address at the same moment create one account.
  One is signed in. The others get the answer for a taken address.
- The address of a deleted account is free. Signing up with it creates a new,
  separate account ([Deleting an account](delete-account.md)).
- A browser that signs up is remembered for 30 days as the browser that created
  the account. That is what lets the emailed link sign it in later, even after
  it signed out.
- The sign-up form sends one request at a time. A double click does not create
  a second request.

### Closed sign-up

- Sign-up runs in one of two modes: open, or closed to everyone except an
  allowlist and invitees.
- The allowlist holds exact addresses and whole domains. Both are compared
  without regard to case.
- A listed domain admits addresses directly at that domain. It does not admit
  its subdomains. With `example.com` listed, `ada@example.com` may sign up and
  `ada@mail.example.com` may not. A lookalike domain that merely ends in the
  same letters, such as `notexample.com`, is not admitted either.
- Anyone else is refused with `403 SIGNUP_CLOSED` and the message "Sign-up is
  by invitation".
- The refusal is the same whether or not the address already has an account.
  It creates nothing, emails nobody and signs nobody in.
- The fields are checked first. A request with an invalid email, password or
  name gets `422 VALIDATION_FAILED`, not `SIGNUP_CLOSED`.
- Refused attempts still count toward the limit of sign-up attempts per client
  address.
- An allowlisted address goes through sign-up exactly as it would while sign-up
  is open, including the answer for an address that already has an account.
- People who already have an account are not affected. They sign in, and they
  accept invitations, as always.

### Signing up from an invitation

- An invitation is sent to one email address. Its link opens the invitation
  page, which offers "Sign in" and "Create account" to a signed-out visitor.
- "Create account" opens the sign-up form with the invited address filled in.
  The address cannot be changed there.
- A sign-up that carries the invitation's token for the same address is
  admitted even while sign-up is closed.
- The token must belong to a live invitation to that same address, compared
  without regard to case. An unknown token, the token of an expired, revoked or
  already accepted invitation, the token of an invitation to another address,
  or an invitation to a deleted organization admits nothing. While sign-up is
  closed that sign-up gets `SIGNUP_CLOSED`. While sign-up is open it proceeds
  as an ordinary sign-up.
- Signing up does not use the invitation up. The same link is then accepted.
- No verification email is sent for a sign-up that carries a live invitation to
  its address. Accepting the invitation verifies the address, because the
  invitation link was sent to that inbox.
- Until the invitation is accepted, the new account is unverified, like any
  other new account.
- After sign-up the browser returns to the invitation, signed in. "Accept
  invitation" joins the organization.
- Accepting needs a session whose email is the invited address. The email may
  be verified or not.
- Invitation links, their 7-day lifetime, roles and workspaces are described in
  [Invitations](../organizations/invitations.md).

### Verifying the email address

- The verification email has the subject "Verify your email for Talewright" and
  a button "Verify your email". It says "For security, this link expires in 24
  hours."
- A verification link works once and for 24 hours.
- Only the newest link works. Asking for a new one makes every earlier one
  invalid.
- An unknown, expired, used or replaced link all get the same answer:
  `400 TOKEN_INVALID`, "This link is invalid or has expired". The answer never
  says which of the four it was.
- What the link does depends on the browser that opens it:

| The browser that opens the link | What happens |
| --- | --- |
| Is signed in to the account | The email is verified. The session stays. No new session starts. |
| Is the browser that signed up, and is not signed in to the account | The email is verified and the browser is signed in to the account. |
| Is neither of the two | Nothing changes until the person chooses a new password. See below. |
| Is signed in to a different account and did not sign this one up | The same as "neither". The page names the account the browser is signed in to. |

- "Neither" covers a different device, a different browser on the same
  computer, a private window, a browser whose cookies were cleared, and the
  built-in browser of a mail app.
- **Choosing a password.** A browser that is neither signed in to the account
  nor the one that signed up must set a new password to verify. Setting it:
  - verifies the email;
  - replaces the password chosen at sign-up;
  - ends every session of the account, on every device;
  - makes every other emailed link of the account invalid;
  - revokes every API key and connected app of the account;
  - signs nobody in. The person then signs in with the new password.
- This is deliberate. If someone else created the account with your address
  and a password they know, opening the link from your own inbox leaves the
  account in your hands alone. And a link opened in a stranger's browser never
  signs that browser in to your account.
- A too-short or missing new password does not use the link up. The link keeps
  working.
- Verifying a second time changes nothing. The date of the first verification
  is kept.

### Other ways an email becomes verified

- **A password reset.** The reset link went to the inbox, so using it verifies
  the address ([Password and email address](password-and-email.md)).
- **Accepting an invitation** sent to the address.
- **Confirming an email change.** The new address is verified by the
  confirmation link.

### Asking for a new link

- A signed-in, unverified person uses "Resend verification email". It sends to
  the account's current address.
- Anyone can also enter an address on the "Link expired or invalid" page and
  choose "Send a new link".
- The answer is the same whether the address has an unverified account, a
  verified account or no account: `202`. Only an unverified account gets an
  email.
- Each new link replaces the previous one.
- Requests are limited to 10 per email address and 100 per client address in
  15 minutes.
- In the app the "Resend verification email" button stays disabled for 30
  seconds after a send.

### What an unverified account can and cannot do

- It can sign in and out, and it stays signed in like any account.
- It can create organizations and workspaces, upload and manage files, create
  API keys, connect apps, invite teammates and accept invitations.
- It can change its name and password, start an email change and manage its
  sessions.
- It can delete itself, with its current password, on the same terms as a
  verified account ([Deleting an account](delete-account.md#an-unverified-account)).
- It cannot delete a workspace or delete an organization. Each answers
  `403 EMAIL_NOT_VERIFIED`, "Verify your email address first".
- An API key or connected app that acts for an unverified member cannot set
  file statuses. The same member can set them in the browser.
- The role is checked before the email. An unverified member who is not allowed
  to delete an organization anyway gets `403 FORBIDDEN`, not
  `EMAIL_NOT_VERIFIED`.
- Once the email is verified, the refused actions work at once. Nothing has to
  be repeated or reloaded on the server side.
- An unverified account is removed 30 days after sign-up if it is still empty
  then: it holds no file or folder, no upload in progress, no other member or
  pending invitation, no API key or connected app, no membership in someone
  else's organization and no pending email change. An empty organization it
  alone owned is deleted with it. An unverified account that holds any of
  these is never removed this way. The full rule is in
  [Deleting an account](delete-account.md#unverified-accounts-are-removed-after-30-days).
- After such a removal the address can sign up again, as after any deletion.

### Emails this feature sends

| Email | Subject | Sent to | When |
| --- | --- | --- | --- |
| Verification | "Verify your email for Talewright" | The new account's address | At sign-up without an invitation, and at every request for a new link by an unverified account |
| Account exists | "You already have a Talewright account" | The existing account's address | When someone signs up with an address that has an account; at most once per account in 15 minutes |

- Every email starts with "Hi {full name},". Words in braces, here and below,
  stand for the real value.
- The account-exists email says "Someone tried to create a Talewright account
  with this email address. An account already exists, so no new account was
  created." It has a "Sign in" button and a link to reset the password.
- The verification email ends: "If you did not request it, you can ignore this
  email."
- Under its button the verification email also prints the full link, after
  "If the button does not work, copy and paste this link into your browser:".

## In the app

### The sign-up page

- Address: `/sign-up`. The sign-in page links to it with "Create account".
- Heading: "Create your account". From an invitation it reads "Join
  {organization} on Talewright".
- Fields: "Full name", "Email" and "Password". Under the password: "At least
  12 characters."
- "Password" has a button at its end that shows what was typed, and hides
  it again.
- Button: "Create account". Below: "Already have an account? Sign in".
- The form checks the fields before it sends anything and reports each problem
  under its field:
  - "Enter your name, up to 200 characters."
  - "Enter a valid email address."
  - "Use at least 12 characters."
  - "Use 128 characters or fewer."
- Fixing a field clears its message.
- If the API refuses a field, the same words appear under that field.
- After too many attempts: "Too many attempts. Try again in 4 minutes." (the
  time varies).
- Any other failure: "Something went wrong. Try again."
- While sign-up is closed and the address is not admitted, the form stays
  filled in and shows "Sign-up is by invitation" with "To create an account,
  open the link in your invitation email."
- A browser that is already signed in does not see the form. It is sent on to
  the app, or to the page it was heading for.

### After "Create account"

- **New address.** The app opens signed in. An account with no organization
  yet lands on "Set up your organization". A sign-up that began from another
  page, such as an invitation, returns there.
- **Address with an account.** The page shows "Check your email" with "We sent
  a message to {address} with the next step." It offers "Use a different
  email", which returns to the form with the name and password kept and the
  address selected.

### The reminder

- Until the email is verified, the app's navigation shows "Verify your email"
  with "Open the link we sent to {address}." and the button "Resend
  verification email". With the navigation collapsed it is an icon labelled
  "Verify your email".
- On "Set up your organization" the reminder is an alert: "Verify your email"
  with "Open the link in the email we sent to {address}. Until then you can do
  everything except delete an organization or a workspace."
- That alert has "Dismiss". Dismissing hides it on that page only, and it is
  back the next time the page opens. The reminder in the navigation cannot be
  dismissed.
- After a resend: "Verification email sent. Check your inbox." The button stays
  disabled for 30 seconds.
- If the resend is limited: "Too many requests. Try again in 4 minutes." Any
  other failure: "Could not send the email. Try again."
- An action refused for lack of verification shows an alert "Verify your
  email" with "To delete this organization, first open the link we sent to
  {address}." (the words after "To" name the action) and its own "Resend
  verification email".
- The account deletion page works for an unverified account as for any
  other.

### The verification page

- The emailed link opens `/verify-email`. The page reads the token and removes
  it from the address bar and the browser history before it does anything
  else. The page sends the link once.
- While it works: "Verifying your email" with "One moment while we confirm your
  link."
- **Verified in a signed-in browser or the browser that signed up:** the app
  opens at its start page with the message "Email verified". The reminder is
  gone.
- **Any other browser:** "Choose a password" with the field "New password" and
  the button "Verify your email". The text reads "Set a password to finish
  verifying your email. It replaces the account's password and signs it out on
  every device. Then sign in with it."
- **A browser signed in to a different account:** the same form, with "You are
  signed in as {address}. This link is for another account. A password set
  here replaces that account's password and signs it out on every device." and
  the link "Continue as {address}".
- After a password is chosen, the sign-in page opens with "Email verified" and
  "Sign in with your new password." A browser signed in to a different
  account opens the app instead, with the message "Email verified".
- **A dead link, or the page opened without a link:** "Link expired or invalid"
  with "Verification links work once and expire after 24 hours. When you ask
  for a new link, only the newest email works. Enter your email to get a new
  link." It has an "Email" field and "Send a new link".
- After "Send a new link": "Check your email" with "If {address} has an account
  waiting for verification, we sent it a new link." and "Use a different
  email".
- **A dead link in a browser signed in to a verified account:** "Email already
  verified" with "{address} is verified." and "Continue to Talewright".
- **Too many attempts or another failure:** "Could not verify your email" with
  "Too many attempts. Try again in 4 minutes." or "Something went wrong. Try
  again.", and the button "Try again".

## For agents

Account operations are for people in a browser. None is an MCP tool. The first
three below are public: they need no session and no credential, and a bearer
token sent with them is ignored. A request that carries both a session cookie
and a bearer token is refused with `401 UNAUTHENTICATED`, reason
`AMBIGUOUS_CREDENTIALS`.

| Operation | Capability ID | Access | MCP |
| --- | --- | --- | --- |
| `POST /v1/auth/sign-up` | `account.sign_up` | public | none |
| `POST /v1/auth/verify-email` | `account.verify_email` | public | none |
| `POST /v1/auth/resend-verification` | `account.verification.resend` | public | none |
| `GET /v1/me` | `auth.me` | session only | none |

`POST /v1/auth/sign-up`

- Body: `email`, `password`, `fullName`, and optionally `invitationToken`.
- `201`: created and signed in. The response sets the session cookie
  `__Host-session` (30 days), and the cookie `__Host-signup` when the browser
  has none. No body.
- `202`: the address already has an account, which was emailed. No session, no
  body.
- `403 SIGNUP_CLOSED`, `422 VALIDATION_FAILED` with `details.field` (`email`,
  `password` or `fullName`), `429 RATE_LIMITED`.

`POST /v1/auth/verify-email`

- Body: `token` (the `token` query parameter of the emailed link) and
  optionally `newPassword`.
- `204`: verified. The response sets `__Host-session` only when the browser
  that signed up was not signed in to the account.
- `422 VALIDATION_FAILED` with `details.field` `newPassword`: this client is
  neither signed in to the account nor the one that signed up, and must send
  `newPassword` (12 to 128 characters). The link stays usable.
- `400 TOKEN_INVALID`, `429 RATE_LIMITED`.

`POST /v1/auth/resend-verification`

- Body: `email`.
- `202` always, when the address is well formed. No body.
- `422 VALIDATION_FAILED` with `details.field` `email`, `429 RATE_LIMITED`.

`GET /v1/me` reports `emailVerified` (see
[Sign-in and sessions](sign-in-and-sessions.md#for-agents)).

A request that changes something (`POST`, `PATCH`, `DELETE`) and carries a
session cookie must send an `Origin` header equal to the app's own origin. Such
a request with any other `Origin` is refused with `403 FORBIDDEN`, with or
without a cookie.

Worked example: sign up, then verify with the token from the emailed link.

```sh
curl -i https://app.usetalewright.com/v1/auth/sign-up \
  -c cookies.txt \
  -H 'Content-Type: application/json' \
  -d '{"email":"ada@example.com","password":"correct horse battery","fullName":"Ada Lovelace"}'
# 201 Created
# set-cookie: __Host-session=...; Max-Age=2592000; Path=/; HttpOnly; SameSite=Lax; Secure
# set-cookie: __Host-signup=...; Max-Age=2592000; Path=/; HttpOnly; SameSite=Lax; Secure

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

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

A refusal has the same shape everywhere:

```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "password must be 12 to 128 characters",
    "details": { "field": "password" }
  },
  "requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
```

## Edge cases

Signing up

1. **The address is typed with spaces around it.** The spaces are removed and
   sign-up continues. Why: they are never part of an address.
2. **The address has a space inside, two `@` signs, or nothing before or after
   the `@`.** Refused with `VALIDATION_FAILED` on `email`. Why: it cannot be an
   address.
3. **The address differs from an existing account only in upper and lower
   case.** It is the same account, so the answer is the one for a taken
   address. Why: addresses are compared without regard to case.
4. **The password starts or ends with spaces.** They are kept and count toward
   the length. Sign-in must use them too. Why: passwords are never trimmed.
5. **The password is made only of spaces.** Accepted if it has 12 to 128 of
   them. Why: the only rule is length.
6. **The password contains emoji or accented letters.** Accepted. Length is
   counted in Unicode code points, so some emoji count as more than one
   character.
7. **The name has spaces around it, or ends in a line break.** They are removed
   and the rest is kept. A control character inside the name is refused.
8. **Several fields are invalid at once.** The form reports all of them under
   their fields. The API reports one, in the order email, password, full name.
9. **Someone signs up twice with the same new address, quickly.** The first
   creates the account. The second gets the answer for a taken address, and
   the account gets one "You already have a Talewright account" email.
10. **Someone signs up again and again with an address that has an account.**
    The holder gets one email per 15 minutes, not one per attempt. After 10
    attempts for the address in 15 minutes, further ones are refused with
    `RATE_LIMITED`.
11. **The address has an account that was never verified.** The answer is the
    one for a taken address. The holder of the inbox can take the account over
    with "Forgot password?": a reset verifies the address and ends every
    session ([Password and email address](password-and-email.md)).
12. **The address belonged to a deleted account.** A new account is created.
    It has no connection to the deleted one.
13. **A request to the API signs up while it carries another account's
    session.** The new account is created and the session cookie is replaced
    with the new account's. The other account's session that the request
    carried is ended in the same step: one browser holds one session. A
    sign-up that signs nobody in (the address has an account) ends nothing.
    In the app this cannot happen: a signed-in browser never sees the
    sign-up form.
14. **Email cannot be sent at the moment.** Sign-up answers
    `503 UNAVAILABLE` with reason `EMAIL_UNAVAILABLE` and creates nothing. Why:
    the account and its verification email are created together or not at all.

Closed sign-up

15. **An address outside the allowlist, with invalid fields.** The fields are
    reported first (`422`). Only a well-formed request learns that sign-up is
    closed.
16. **An address outside the allowlist that already has an account.** The same
    `SIGNUP_CLOSED` as for an unknown address, and no email. Why: the refusal
    must not reveal who has an account.
17. **An allowlisted address typed in another case.** Admitted.
18. **An address at a subdomain of a listed domain.** Refused.
19. **An invited person signs up without opening their invitation link in that
    browser.** Refused with `SIGNUP_CLOSED`, because the request carries no
    invitation. Opening the link first and choosing "Create account" works.
20. **An invited person's invitation was revoked or expired, or a newer
    invitation replaced its link.** The old link admits nothing. They need the
    newest invitation email.
21. **Someone uses another person's invitation link to sign up with their own
    address.** Refused. The invitation admits only the address it was sent to.

Signing up from an invitation

22. **The invitee creates the account and never accepts.** The account exists
    and is unverified. No verification email was sent. "Resend verification
    email" sends one.
23. **The invitation is revoked after the account was created.** The account
    stays. It is unverified and belongs to no organization. It can still be
    verified with "Resend verification email" and used on its own.
24. **The invitee already had an account.** They choose "Sign in" on the
    invitation page instead. Signing up again with the address gets the answer
    for a taken address.
25. **The browser still holds an invitation link from earlier and the person
    signs up with a different address.** The invitation does not match, so it
    is ignored: an ordinary sign-up while sign-up is open, `SIGNUP_CLOSED`
    while it is closed.

Verifying

26. **The link is opened on a phone, the account was created on a laptop.** The
    phone shows "Choose a password". Setting one signs the laptop out. Why: the
    phone is neither signed in to the account nor the browser that signed up.
27. **The link is opened in the mail app's built-in browser or a private
    window.** The same: "Choose a password".
28. **The person signed up, signed out, and opens the link in the same
    browser.** The email is verified and the browser is signed in. Why: it is
    remembered as the browser that signed up.
29. **The person signed up, cleared the browser's cookies, and opens the
    link.** "Choose a password". Why: the browser can no longer be recognized.
30. **The browser that signed up is now signed in to a different account.** The
    link verifies the new account and signs the browser in to it. The other
    account's session in that browser is ended in the same step; its sessions
    in other browsers stay.
31. **A browser signed in to a different account, which did not sign this one
    up, opens the link.** "Choose a password", with the name of the account the
    browser is signed in to and "Continue as {address}". If a password is set,
    the browser stays signed in to its own account and the app opens that
    account's start page with the message "Email verified", because the
    sign-in page is skipped for a signed-in browser.
32. **The link is opened twice.** The first verifies. The second is a dead
    link: "Email already verified" in a browser signed in to the verified
    account, "Link expired or invalid" elsewhere.
33. **Two requests use the same link at the same moment.** Exactly one
    succeeds.
34. **An older link is opened after a newer one was requested.** Dead. Only the
    newest works.
35. **The link is 24 hours old.** Dead. Ask for a new one.
36. **On "Choose a password", the password is too short.** Reported under "New
    password". The link is not used up.
37. **Someone else created an account with your address and you open the
    link.** In your browser the page asks for a new password. Setting one makes
    the account yours: their password stops working, their sessions end and
    their API keys and connected apps are revoked. If you ignore the email, the
    account stays unverified.
38. **The account was verified another way while a verification link was still
    outstanding.** A password reset, a confirmed email change or an accepted
    invitation makes the outstanding link invalid.
39. **The email address is changed before the first one was verified.** The
    verification link sent to the first address keeps working until the change
    is confirmed. Confirming the change verifies the new address and makes the
    old link invalid.
40. **The account was deleted before the link was opened.** Dead link.

Asking for a new link

41. **"Send a new link" for an address with a verified account, or with no
    account.** The page shows the same "Check your email". Nothing is sent.
42. **"Resend verification email" pressed twice quickly.** One request is
    sent. Why: each send would make the previous link invalid.
43. **More than 10 requests for one address in 15 minutes.** Refused with
    `RATE_LIMITED`, wherever they come from.

## Errors

| Code | HTTP | Meaning here | What to do |
| --- | --- | --- | --- |
| `VALIDATION_FAILED` | 422 | A field is invalid. `details.field` names it: `email` ("email must be an email address of at most 320 characters"), `password` ("password must be 12 to 128 characters"), `fullName` ("fullName must be 1 to 200 characters" or "fullName must not contain control characters"). On resend: `email` ("email must be 1 to 320 characters"). | Correct the field and send again. |
| `VALIDATION_FAILED` | 422 | On verify, `details.field` is `newPassword`: "newPassword is required to verify from another browser than the one that signed up", or "newPassword must be 12 to 128 characters". | Send the same token again with a valid `newPassword`. The link is still usable. |
| `VALIDATION_FAILED` | 422 | The body is not valid JSON or lacks a required field. `details` is `null`. | Fix the request. |
| `SIGNUP_CLOSED` | 403 | "Sign-up is by invitation". Sign-up is closed to this address. | Open the link in an invitation email and create the account from there, or ask an owner or admin for an invitation. |
| `TOKEN_INVALID` | 400 | "This link is invalid or has expired". The verification link is unknown, expired, used or replaced. | Ask for a new link. |
| `EMAIL_NOT_VERIFIED` | 403 | "Verify your email address first". The action needs a verified email. | Open the verification link, then repeat the action. |
| `RATE_LIMITED` | 429 | "Too many attempts; try again later". `details.retryAfterSeconds` and the `Retry-After` header give the wait in seconds. | Wait that long. Attempts made while limited do not make the wait longer. |
| `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. |
| `UNAUTHENTICATED` | 401 | Reason `AMBIGUOUS_CREDENTIALS`: the request carried both a session cookie and a bearer token. | Send one of them. |
| `UNAVAILABLE` | 503 | Reason `EMAIL_UNAVAILABLE`: email cannot be sent right now. Nothing was created or changed. | Try again later. |

## Limits

| What | Limit |
| --- | --- |
| Email address | At most 320 characters |
| Password | 12 to 128 characters |
| Full name | 1 to 200 characters after trimming |
| Verification link lifetime | 24 hours, single use, newest only |
| Session started by sign-up | 30 days |
| How long a browser is remembered as the one that signed up | 30 days |
| How long an unverified account that holds nothing is kept | 30 days from sign-up, checked about once an hour |
| Sign-up attempts for one email address | 10 in 15 minutes, from all clients together |
| Sign-up attempts from one client address | 100 in 15 minutes, including attempts refused because sign-up is closed |
| "You already have a Talewright account" emails | 1 per account in 15 minutes |
| Requests for a new verification link for one email address | 10 in 15 minutes |
| Requests for a new verification link from one client address | 100 in 15 minutes |
| Verification attempts from one client address | 100 in 15 minutes |
| "Resend verification email" button | Disabled for 30 seconds after a send |

- A 15-minute window starts at the first attempt. It does not move when
  further attempts are refused.
- Each action counts separately. Sign-up attempts do not use up sign-in
  attempts.
- A request refused because a field is malformed is not counted.

## Questions and answers

**Do I have to verify my email before I can use Talewright?**
No. A new account is signed in at once and can create organizations, upload
files and invite people. Verification is needed only to delete a workspace or
an organization, and to set file statuses through an API key or connected app.
An account that stays unverified and empty is removed after 30 days.

**I did not get the verification email. What now?**
Check the address shown in the reminder, then choose "Resend verification
email". Only the newest email's link works. If the address is wrong, change it
under Settings, Security ([Password and email address](password-and-email.md));
confirming the new address verifies the account.

**How long does the verification link work?**
24 hours, and once.

**Why does the link ask me to choose a new password?**
Because the browser that opened it is not signed in to the account and is not
the browser that created it. That happens on another device, in a private
window, in a mail app's built-in browser, or after cookies were cleared. The
new password replaces the old one and signs the account out everywhere.

**I chose a new password from the link. Why was I signed out on my laptop?**
Choosing a password from a verification link ends every session of the account
and revokes its API keys and connected apps. Sign in again with the new
password.

**I got "You already have a Talewright account". What does it mean?**
Someone, perhaps you, tried to sign up with your address. No account was
created and yours was not changed. Sign in, or reset your password if you
forgot it. If it was not you, you can ignore the email.

**I got a verification email but never signed up.**
Someone created an account with your address. You can ignore the email: the
account stays unverified. To take the account, open the link in your own
browser and choose a password; that locks the other person out.

**The sign-up page says "Check your email" but I am not signed in. Why?**
The address already has an account. Talewright emailed that address instead of
creating a second account. Use "Sign in", or "Forgot password?" on the sign-in
page.

**The sign-up page says "Sign-up is by invitation". How do I get in?**
Sign-up is closed to your address. Ask an owner or admin of an organization to
invite you, then open the link in the invitation email and choose "Create
account".

**I was invited. Do I still have to verify my email?**
Not separately. Accepting the invitation verifies the address, and no
verification email is sent when you create the account from the invitation.

**I was invited but sign-up still refuses me.**
The sign-up must start from your invitation link, in the same browser, and use
the invited address. An expired, revoked or replaced invitation does not count.
Open the newest invitation email.

**Can two accounts share an email address?**
No. Addresses are unique without regard to upper and lower case.

**Can I sign up with the address of an account I deleted?**
Yes. It creates a new account. Nothing of the deleted one comes back.

**What are the password rules?**
12 to 128 characters. Any characters. Nothing is trimmed.

**Is my name checked?**
Only its length (1 to 200 characters) and that it holds no control characters.
You can change it later under Settings, Account.

**What can I not do before verifying?**
Delete a workspace, delete an organization, and set file statuses through an
API key or connected app. Deleting your own account works without verifying.

**Does an unverified account expire?**
Only while it is empty. An account that never verified its email and holds
nothing is removed 30 days after sign-up. One that holds a file, a folder, an
upload in progress, another member, a pending invitation, an API key, a
connected app or a pending email change is kept, however old it is.

**Can an agent or a script create accounts?**
The operations are public REST calls, so a script can call them. They are not
MCP tools and no API key scope covers them. The limits per email address and
per client address apply.

**Does signing up tell others whether my address has an account?**
A person who tries to sign up with your address sees "Check your email" instead
of being signed in, so they can tell. You get an email about it. Asking for a
verification link or a password reset never reveals it.

**I pressed "Resend verification email" and the button is greyed out.**
It stays disabled for 30 seconds after each send.

## Related pages

- [Sign-in and sessions](sign-in-and-sessions.md)
- [Password and email address](password-and-email.md)
- [Deleting an account](delete-account.md)
- [Invitations](../organizations/invitations.md)
- [Credentials and scopes](../agents/credentials.md)
- [Errors](../reference/errors.md)
- [Limits](../reference/limits.md)

