# Invitations

## Summary

An invitation asks one email address to join an organization. It names the
organization role the person gets and, optionally, the workspaces they join.
Talewright emails the address a link. The link works once and for 7 days.

Only the person who holds the invited address can accept: they sign in, or
create an account, with exactly that address. Accepting adds them to the
organization and the named workspaces at once and verifies their email
address.

Owners and admins invite, see the pending invitations and revoke them.
Inviting the same address again resends the invitation with a new link.

When sign-up is closed, an invitation is also the way a new person gets an
account.

## Who can do what

| Action | Owner | Admin | Member | Someone outside | Credential |
| --- | --- | --- | --- | --- | --- |
| Invite as member | Yes | Yes | No | No | No |
| Invite as admin | Yes | Yes | No | No | No |
| Invite as owner | Yes | No | No | No | No |
| Resend (invite a pending address again) | Yes | Yes, unless the new role or the pending invitation's role is owner | No | No | No |
| List pending invitations | Yes | Yes | No | No | No |
| Revoke an invitation, also an owner's | Yes | Yes | No | No | No |
| See what a link offers (preview) | Anyone who has the link, signed in or not | | | | |
| Accept | The signed-in account whose email is the invited address | | | | No |

- Every operation except the preview needs a person signed in with a
  browser. A credential gets `403 FORBIDDEN` with `details.reason`
  `SESSION_REQUIRED`.
- Neither inviting nor accepting needs a verified email.

## How it works

### Sending an invitation

- An invitation has three parts: an email address, an organization role, and
  zero or more workspaces of the organization.
- Owners invite with any role. Admins invite admins and members. Only owners
  invite owners.
- The address must look like an email address: something before one `@`,
  something after it, no spaces or control characters, at most 320
  characters.
- The address is stored trimmed and in lower case. `Ada@Example.com`,
  `ada@example.com` and ` ada@example.com ` are the same invitation.
- The role is `owner`, `admin` or `member`.
- The workspaces must be live workspaces of this organization. A workspace
  of another organization, a deleted workspace or an unknown ID is refused.
- An invitation can name at most 100 workspaces. Naming one twice counts
  once.
- An invitation can name no workspace at all. The person then joins the
  organization only. A plain member invited that way can open no workspace
  until an owner or admin adds them to one. They still read the member list
  and the organization folder.
- In each named workspace the person gets a workspace membership with the
  same role as their organization role.
- An invitation carries no personal message. The email's text is fixed.
- An invitation cannot be declined. The invited person ignores the email, or
  chooses "Continue without joining" on the invitation page. The invitation
  then expires by itself, or an owner or admin revokes it.
- An invitation goes to one email address. There is no invite link to share
  with several people: the link works only for an account with the invited
  address.
- An invitation does not create an account and does not reserve the
  address. Nothing exists for the person until they create an account
  themselves.
- An address that already belongs to a member of the organization cannot be
  invited: `409 CONFLICT`.
- An address can be invited whether or not it has a Talewright account.
- There is one invitation per address per organization. The same address can
  hold invitations to several organizations at once.
- The answer is `201` with the invitation and `resent`, which says whether
  an existing pending invitation was resent.

The checks happen in this order. The first that fails decides the answer:

1. Not signed in: `401 UNAUTHENTICATED`.
2. The organization is unknown, deleted or not yours: `404 NOT_FOUND`.
3. The request is not the expected JSON, for example `role` is not a role:
   `422 VALIDATION_FAILED`.
4. You are a plain member, or an admin inviting an owner: `403 FORBIDDEN`.
5. The address is not a valid email address: `422 VALIDATION_FAILED` on
   `email`.
6. More than 100 workspaces: `422 VALIDATION_FAILED` on `workspaceIDs`.
7. You, or the organization, sent too many invitations this hour:
   `429 RATE_LIMITED`.
8. A workspace is not a live workspace of this organization:
   `422 VALIDATION_FAILED` on `workspaceIDs`.
9. The address belongs to a member: `409 CONFLICT`.
10. Otherwise the invitation is stored and emailed: `201`.

### The email

- Every invitation and every resend sends one email to the invited address.
  There are no reminders.
- Subject: "{organization} invited you to join Talewright".
- Heading: "{organization} invited you to Talewright".
- Text: "{inviter} invited you. You have been invited to join
  "{organization}" as a member." (or "as an admin", "as an owner"). When the
  invitation names workspaces, it continues: "You get access to "{workspace}" and "{workspace}"." The
  workspaces are listed by name, in alphabetical order.
- Button: "Accept invitation". It opens the invitation page of the app with
  the link's secret.
- Below the button: "If you already have a Talewright account, sign in
  before accepting so we can add you immediately."
- At the end: "This invitation was sent to {address}. If you were not
  expecting it, you can safely ignore this message."
- The email shows the organization's and workspaces' names as they are when
  it is sent. A later rename does not change an email already sent.
- A resent invitation's email names every workspace the invitation now
  grants.

### Expiry

- An invitation lasts 7 days from the moment it is sent or resent. The 7
  days cannot be set to another length.
- After that it is expired. Its link answers `400 TOKEN_INVALID`, and it is
  no longer in the pending list.
- An expired invitation is not extended. Invite the address again: that
  makes a fresh invitation with a new link and a new 7 days.
- Expired invitations are cleared away automatically.

### Resending

There is no separate resend action. Inviting an address that has a pending
invitation resends it:

- It stays one invitation, with the same ID. The answer has `resent: true`.
- A new link is emailed. The earlier link stops working at once.
- The role becomes the role of the new request.
- The inviter becomes the person who resent it.
- An admin cannot resend a pending invitation whose role is owner, with any
  new role: `403 FORBIDDEN`. The invitation, its inviter and its link stay as
  they were. Owners resend any invitation.
- The workspaces become the earlier workspaces plus the new ones. A resend
  never takes a workspace away.
- The 7 days start again.
- It moves to the top of the pending list.
- The address may be typed in another case or with spaces around it. It is
  still the same invitation.
- A resend counts against the hourly limits like a new invitation.

Inviting an address whose invitation has **expired** is not a resend. The old
invitation is replaced outright: only the new role and the new workspaces
apply, and `resent` is `false`.

To take a workspace away from a pending invitation, revoke it and invite
again.

### The pending list

- Owners and admins see the organization's pending invitations, newest
  first.
- Each entry has the address, the role, the workspaces, who invited, when it
  was sent and when it expires.
- Expired, accepted and revoked invitations are not listed.
- A workspace that is deleted is left out of an entry's workspaces. It is
  back in the entry if the workspace is restored.
- The list is paged: 50 entries by default, at most 100 a page.
- Members cannot see the list: `403 FORBIDDEN`.

### Revoking

- Owners and admins revoke any invitation of the organization, including
  one sent by someone else and one that invites an owner.
- Revoking deletes the invitation. Its link answers `400 TOKEN_INVALID` from
  then on.
- The invited person is not told. No email is sent.
- A revoked invitation cannot be brought back. Invite again to send a new
  one.
- Revoking an invitation that was accepted or revoked a moment earlier
  answers `404 NOT_FOUND`.

### Invitations end with their inviter's rights

An invitation lasts only as long as the person who sent it could still send
it. The moment that stops being true, the invitation is deleted and its link
stops working:

- The inviter is removed from the organization: all their pending
  invitations for it are deleted.
- The inviter leaves the organization: the same.
- The inviter deletes their account: all their pending invitations, in every
  organization, are deleted.
- The inviter is made a plain member: all their pending invitations for the
  organization are deleted.
- An owner is made an admin: the owner invitations they sent are deleted.
  Their admin and member invitations stay.

Invitations sent by other people are never affected. An invitation that was
resent belongs to the person who resent it.

### What a link shows before it is accepted

- Anyone who holds a link can open it, signed in or not.
- The preview shows exactly four things: the invited address, the
  organization's name, the inviter's name and the role.
- It shows nothing else: no workspaces, no members, no files.
- A link that is unknown, expired, already used, replaced by a resend,
  revoked, or that belongs to a deleted organization shows nothing. All of
  them answer `400 TOKEN_INVALID`, with no hint which it was.

### Accepting

- Accepting needs a signed-in account whose email address is the invited
  address. Upper and lower case do not matter. Everything else must match:
  `name+work@example.com` is not `name@example.com`.
- The account may be verified or unverified.
- Accepting does all of this together:
  - The account joins the organization with the invited role.
  - It gets a workspace membership, with the same role, in every named
    workspace that is live at that moment.
  - Its email address becomes verified, if it was not. Only the holder of
    that inbox received the link. A verification link the account was sent
    earlier stops working.
  - The invitation is used up and deleted. The link never works again.
- The answer is `200` with the organization's workspaces the account can now
  open, sorted by name.
- Nobody is emailed when an invitation is accepted.
- An invitation is accepted once. A second attempt, also a double click or
  two browsers at once, gets `400 TOKEN_INVALID`.

The checks happen in this order:

1. Not signed in: `401 UNAUTHENTICATED`.
2. The link is unknown, expired, used, replaced, revoked or of a deleted
   organization, or its inviter may no longer send it:
   `400 TOKEN_INVALID`.
3. The account's email is not the invited address: `403 FORBIDDEN`. The link
   stays usable.
4. The account is already a member of the organization: `409 CONFLICT`. The
   link stays usable and nothing about the account changes.
5. Otherwise the account joins: `200`.

### Closed sign-up and invitations

Sign-up can be closed, so that only chosen addresses can create an account.
Invitations keep working when it is:

- A new person creates an account for the invited address by starting from
  their invitation link. The sign-up carries the invitation's secret, which
  admits it.
- The secret must belong to a live invitation to that very address. A made
  up secret, a used, revoked or expired one, or the secret of an invitation
  to another address does not admit the sign-up. All answer
  `403 SIGNUP_CLOSED`.
- Signing up this way does not use up the invitation. It is accepted
  afterwards, as a separate step.
- Signing up without the secret answers `403 SIGNUP_CLOSED`, whether or not
  the address has an invitation or an account, unless the address is one of
  those allowed to sign up.
- An account that already exists is not affected by closed sign-up. It signs
  in and accepts invitations as usual.

In every case, open or closed: an account created from a live invitation to
its own address gets no verification email. Accepting the invitation
verifies the address. See
[Sign-up and email verification](../accounts/sign-up.md).

### While the organization is deleted

- Invitations of a deleted organization cannot be previewed or accepted.
  Their links answer `400 TOKEN_INVALID`.
- Their 7 days keep running.
- If the organization is restored before an invitation expires, its link
  works again.
- New invitations cannot be sent to a deleted organization.

## In the app

### Inviting

**Settings > Organization > Members** has the section "Invitations" for
owners and admins. Members do not see it.

1. Choose "Invite member".
2. The dialog "Invite member" says "We email them a link to join
   {organization}. It works once and expires after 7 days."
3. Fill in "Email".
4. Choose a "Role". "Member" is chosen to start with. The choices and their
   descriptions:
   - "Member": "Works in the workspaces they are added to."
   - "Admin": "Manages members, invitations, workspaces and exports, and
     reaches every workspace."
   - "Owner", for owners only: "Everything an admin can do, plus managing
     owners and deleting the organization."
5. For the role "Member", tick the "Workspaces" they join. The hint reads
   "They join the chosen workspaces with the same role. You can assign
   workspaces later." When the organization has exactly one workspace, it is
   ticked already.
6. Choose "Send invitation".

- The workspace choice is shown only for "Member". Admins and owners reach
  every workspace anyway, so the app sends no workspaces for them.
- After sending, the app shows "Invitation sent to {address}", or
  "Invitation resent to {address}" when the address already had a pending
  invitation.
- A double click sends one invitation and one email.

Messages in the dialog:

| Message | When |
| --- | --- |
| "Enter a valid email address." | The address is not an email address. |
| "This address belongs to a member." | The address is already a member of the organization. |
| "Choose workspaces of this organization." | A chosen workspace is no longer a live workspace of the organization, for example because it was deleted while the dialog was open. |
| "Too many invitations. Try again {when}." | An hourly limit was reached. |
| "Your role no longer allows that. The page now shows what you can do." | Your role was lowered since the page loaded, or you are an admin and the address has a pending owner invitation. The dialog closes. |

### The pending list in the app

The "Invitations" section says "Pending invitations. Revoking one stops its
link from working."

- The table "Pending invitations" has the columns "Email", "Role" (such as
  "Member in Brand, Campaigns"), "Invited by" and "Expires".
- With nothing pending it says "No pending invitations."
- "Load more" shows further invitations.

### Revoking in the app

1. Choose "Revoke" on the invitation's row.
2. The confirmation "Revoke invitation?" says "The link sent to {address}
   stops working."
3. "Revoke invitation" revokes it. "Cancel" keeps it.
4. The app shows "Invitation revoked" and the row disappears.

If it fails the section says "Could not revoke the invitation. Try again."

### Opening an invitation link

The link in the email opens the invitation page.

- The page takes the secret out of the address bar and the browser history
  at once.
- While it checks the link it shows "Opening your invitation": "One moment
  while we check the link."
- A good link shows "Join {organization}" and "{inviter} invited you to join
  {organization} as a member." (or "as an admin", "as an owner").
- A bad link shows "Link expired or invalid": "Invitation links work once,
  expire after 7 days and stop working when a newer invitation is sent. Open
  the latest invitation email, or ask for a new one." The button "Continue
  to Talewright" leaves the page.
- If the link cannot be checked at all: "Could not open the invitation",
  "Something went wrong. Try again.", with "Try again".

What comes next depends on who is looking.

### Signed out

- The page says "Sign in or create an account with {address}." and offers
  "Sign in" and "Create account".
- The browser keeps the invitation while you do either, so you come back to
  it afterwards. The link's secret is not passed along in any address.

**You have no account.** Choose "Create account".

- The page is titled "Join {organization} on Talewright".
- "Email" already holds the invited address and cannot be changed.
- You enter your name and a password and choose "Create account".
- You are signed in at once and are back on the invitation. You do not have
  to verify your email first, and no verification email is sent.
- Choose "Accept invitation".

**You have an account with the invited address.** Choose "Sign in".

- The sign-in page starts with the invited address.
- After signing in you are back on the invitation. Choose "Accept
  invitation".

### Signed in with the invited address

- The page says "Signed in as {address}." and offers "Accept invitation".
- After accepting you land in Files & Assets of the first workspace you can
  now open, and the app shows "You joined {organization}".
- If the invitation gave you no workspace, the page changes to "You joined
  {organization}": "An owner or admin adds you to its workspaces." with
  "Continue to Talewright".
- A double click accepts once.

### Signed in with another address

- The page says "Signed in as {your address}." and "This invitation is for
  {invited address}": "Sign in with that address to accept it."
- "Accept invitation" is not offered.
- "Sign in with another account" signs you out and opens the sign-in page.
  The invitation is kept, so signing in with the right account brings you
  back to it.
- "Continue without joining" forgets the invitation in this browser and
  takes you home. The link itself keeps working.

### Already a member

If the account already belongs to the organization, accepting shows "You are
already a member": "You already belong to {organization}." with "Continue to
Talewright". The invitation is left as it is.

### A kept invitation comes first

- From the moment you open an invitation link, the browser keeps it until
  you accept it, until it turns out to be invalid or you turn out to be a
  member already, until you choose "Continue without joining", or until you
  sign out.
- While it is kept, opening the app's home takes you to the invitation
  first, also if your account already has workspaces.
- An invitation that turned out to be invalid is forgotten, so "Continue to
  Talewright" does not bring you back to it.

### Sign-up closed

When sign-up is closed and someone tries to create an account without an
invitation, the sign-up page shows "Sign-up is by invitation": "To create an
account, open the link in your invitation email."

## For agents

Invitations are for people. No invitation operation is open to a credential
and none is an MCP tool. The preview is public, so it needs no credential at
all.

| Operation | Capability ID | Access |
| --- | --- | --- |
| `POST /v1/organizations/{organizationID}/invitations` | `organizations.invitations.create` | session only |
| `GET /v1/organizations/{organizationID}/invitations` | `organizations.invitations.list` | session only |
| `DELETE /v1/organizations/{organizationID}/invitations/{invitationID}` | `organizations.invitations.revoke` | session only |
| `GET /v1/invitations/{token}` | `invitations.preview` | public |
| `POST /v1/invitations/{token}/accept` | `invitations.accept` | session only |

`{token}` is the `token` value of the emailed link.

### Create

Body:

```json
{
  "email": "ivy@example.com",
  "role": "member",
  "workspaceIDs": ["01928f40-1111-7aaa-8bbb-000000000001"]
}
```

`workspaceIDs` may be left out; it then counts as empty. Answer, `201`:

```json
{
  "id": "01928f55-aaaa-7bbb-8ccc-0000000000aa",
  "email": "ivy@example.com",
  "role": "member",
  "workspaceIDs": ["01928f40-1111-7aaa-8bbb-000000000001"],
  "invitedBy": { "id": "01928f3e-0000-7000-8000-00000000000a", "fullName": "Ada Aziz" },
  "createdAt": "2026-11-01T10:00:00Z",
  "expiresAt": "2026-11-08T10:00:00Z",
  "resent": false
}
```

The link's secret is never in an API answer. It exists only in the email.

### List

`GET .../invitations` takes `limit` (1 to 100, default 50) and `cursor`. It
answers `{"items": [...], "nextCursor": ...}` with the same fields as above,
without `resent`.

### Preview

`GET /v1/invitations/{token}` answers `200` with exactly:

```json
{
  "email": "ivy@example.com",
  "organizationName": "Acme",
  "inviterName": "Ada Aziz",
  "role": "member"
}
```

### Accept

`POST /v1/invitations/{token}/accept` takes no body. It answers `200` with
the list of the organization's workspaces the account now reaches, each with
`id`, `name`, `organizationID`, `organizationName` and `role`. The list is
empty when the invitation gave no workspace.

### What an agent can do instead

An agent that needs a person added asks an owner or admin to invite them.
It can check the result afterwards with `organizations_members_list` or
`workspaces_members_list`. See
[Members and roles](members-and-roles.md#for-agents).

## Edge cases

| Situation | What happens | Why |
| --- | --- | --- |
| An admin invites someone as owner | `403 FORBIDDEN`. No invitation, no email. | Only owners invite owners. |
| A member invites anyone | `403 FORBIDDEN`. | Members do not invite. |
| The address already belongs to a member | `409 CONFLICT`. The app says "This address belongs to a member." | They are already in. Change their role or workspaces instead. |
| You invite your own address | `409 CONFLICT`. | You are a member. |
| The address is not an email address | `422 VALIDATION_FAILED` on `email`. | The address is checked before anything is sent. |
| A workspace of another organization is named | `422 VALIDATION_FAILED` on `workspaceIDs`. | Only this organization's workspaces can be named. |
| A deleted workspace is named | `422 VALIDATION_FAILED` on `workspaceIDs`. | A deleted workspace cannot be named. |
| The role is not `owner`, `admin` or `member` | `422 VALIDATION_FAILED`. | Unknown roles are refused. |
| A member is invited with no workspace | The invitation is valid. After accepting they belong to the organization and see "You joined {organization}": "An owner or admin adds you to its workspaces." | Workspaces can be assigned later. |
| An admin or owner is invited with workspaces through the API | They get workspace memberships with that role in those workspaces, and reach every other workspace through their role as well. | The named workspaces are always granted. |
| The same address is invited again while pending | One invitation, a new link, `resent: true`. The first link answers `400 TOKEN_INVALID`. | Only the newest link works. |
| It is invited again in other letter case or with spaces | The same: a resend to the stored, lower-case address. | An address is one address however it is typed. |
| It is invited again with other workspaces | The invitation now grants both sets. The email names all of them. | A resend adds workspaces, never removes them. |
| It is invited again with another role | The new role replaces the old one. | The newest request decides the role. |
| An admin invites, as member or admin, an address an owner had invited as owner | `403 FORBIDDEN`. The invitation stays an owner invitation sent by the owner, and its link keeps working. | Admins never change an owner invitation, as they never change an owner. |
| An admin invites an address whose owner invitation has expired | A fresh invitation with the admin's role and workspaces: `resent: false`. | An expired invitation grants nothing and is replaced outright. |
| An admin invites, as owner, an address that has a pending invitation | `403 FORBIDDEN`. The existing invitation is unchanged. | Admins never send owner invitations, also not as a resend. |
| An address is invited again after its invitation expired | A fresh invitation: `resent: false`, only the new workspaces. | An expired invitation is replaced, not continued. |
| The 51st invitation of one person within an hour | `429 RATE_LIMITED` with `Retry-After`. The app shows "Too many invitations. Try again in {n} minutes." | Each inviter sends at most 50 an hour, counted across all their organizations. |
| The 201st invitation to one organization within an hour | `429 RATE_LIMITED`, whoever sends it. | Each organization sends at most 200 an hour. |
| An invitation is refused because the address is a member, a workspace is not valid, or an admin resends a pending owner invitation | It still counted toward the hourly limits. | The limits count attempts that reach that point, not only invitations sent. |
| An invitation is refused because a member invites, an admin invites as owner, or the address is malformed | It did not count toward the limits. | Those checks come before the count. |
| The inviter is removed, leaves or deletes their account while invitations are pending | Those invitations are deleted. Their links answer `400 TOKEN_INVALID`. Other people's invitations stay. | An invitation lasts only while its sender could still send it. |
| An owner who invited an owner and a member is made admin | The owner invitation is deleted. The member invitation stays. | An admin could still have sent the member invitation. |
| An invitation is revoked while its link is being accepted | Exactly one of the two happens. Either the person joins and the revoke gets `404 NOT_FOUND`, or the invitation is revoked and the accept gets `400 TOKEN_INVALID`. | The two are handled one after the other. |
| "Accept invitation" is clicked twice | The person joins once. | The app sends one accept at a time, and a link is used up by its first accept. |
| The link is opened signed out | The preview shows. Accepting through the API answers `401 UNAUTHENTICATED`. | Accepting needs to know who you are. |
| The link is accepted by an account with another address | `403 FORBIDDEN`. The account is not added and the link keeps working. | Only the invited address may accept. |
| The invitee forwards the email to a colleague | The colleague sees the preview but cannot accept with their own account. | The link is bound to the invited address. |
| The account's address differs only in letter case | It is accepted. | Addresses are compared ignoring case. |
| The invitee uses `name+tag@example.com` but was invited as `name@example.com` | `403 FORBIDDEN`. | Apart from case, the address must be identical. |
| The invitee changes their account's email to the invited address, then accepts | It works. | The check uses the account's current address. |
| The account is already a member | `409 CONFLICT`. Nothing changes, and the invitation stays. | There is nothing to join. |
| An unverified account accepts | It joins and its email becomes verified. | Only the holder of the invited inbox received the link. |
| An unverified account accepts and then opens the verification link it was sent at sign-up | `400 TOKEN_INVALID`, as for a used link. | Accepting verified the address, so the verification link is spent. |
| The link is used a second time | `400 TOKEN_INVALID`. The app shows "Link expired or invalid". | A link works once. |
| A made-up link is opened | `400 TOKEN_INVALID`, the same as for a used or expired one. | The answer must not reveal which links ever existed. |
| The invitation expires while the invitee is on the invitation page | Accepting answers `400 TOKEN_INVALID` and the page shows "Link expired or invalid". | Expiry is checked at the moment of accepting. |
| A named workspace is deleted before the invitee accepts | They join the organization and the other named workspaces. They are not added to the deleted one, also not if it is restored later. | Accepting adds live workspaces only, and the invitation is used up. |
| A named workspace is deleted and restored before the invitee accepts | They join it as invited. | The invitation kept its workspaces. |
| The organization is renamed after the email was sent | The email still shows the old name. The invitation page shows the new one. The link works. | Emails are not rewritten. |
| The organization is deleted while invitations are pending | The links answer `400 TOKEN_INVALID`. If it is restored before they expire, they work again. | A deleted organization accepts nobody. |
| The invitee has an account and chooses "Create account" | No second account is made. The existing account gets an email saying it already exists. They sign in instead. | One address has one account. |
| The invitee creates an account from the link but never accepts | The account exists, signed in and unverified. It is not a member of anything. The invitation stays pending until it expires. | Creating an account and accepting are separate steps. |
| Sign-up is closed and the invitee signs up without their link | `403 SIGNUP_CLOSED`. | Only the invitation's secret admits a new address. |
| Sign-up is closed and someone signs up with another person's invitation secret | `403 SIGNUP_CLOSED`. No account is made. | The secret admits only the address it was sent to. |
| Sign-up is closed and the invitation was revoked | `403 SIGNUP_CLOSED`. | A revoked invitation admits nobody. |
| Sign-up is closed and the invitee already has an account | They sign in and accept as usual. | Closed sign-up stops new accounts, not existing ones. |
| Sign-up is open and a stranger signs up carrying someone else's invitation secret | Their account is created and gets the normal verification email. The invitation is untouched. | The secret spares a verification email only for the invited address. |
| An account with workspaces opens the app while an invitation is kept in the browser | The invitation opens first. "Continue without joining" forgets it. | A kept invitation comes before anything else. |
| Someone signs out on a shared computer after opening a link | The kept invitation is forgotten in that browser. The emailed link still works. | The next person on that computer must not be handed it. |
| A member opens the Members page | No "Invitations" section, and the pending list is not requested. | Members cannot see invitations. |
| Email cannot be sent at the moment of inviting | `503 UNAVAILABLE` with `details.reason` `EMAIL_UNAVAILABLE`. No invitation is stored. | An invitation without its email would be useless. |

## Errors

| Code | Status | When | What to do |
| --- | --- | --- | --- |
| `TOKEN_INVALID` | 400 | The link is unknown, expired, used, replaced by a resend, revoked, of a deleted organization, or its inviter may no longer send it. | Open the newest invitation email, or ask for a new invitation. |
| `UNAUTHENTICATED` | 401 | Not signed in, for everything but the preview. | Sign in. |
| `FORBIDDEN` | 403 | A member invites, lists or revokes; an admin invites an owner or resends a pending owner invitation; the account accepting has another email address. | Ask an owner or admin; or sign in with the invited address. |
| `FORBIDDEN`, reason `SESSION_REQUIRED` | 403 | A credential calls an invitation operation. | A person does this in a browser. |
| `SIGNUP_CLOSED` | 403 | Creating an account while sign-up is closed, without a live invitation to that address. | Start from the invitation link. |
| `NOT_FOUND` | 404 | The organization is unknown, deleted or not yours; the invitation to revoke does not exist in it. | Check the ID; reload the pending list. |
| `CONFLICT` | 409 | Inviting an address that belongs to a member ("this address belongs to a member of the organization"); accepting when already a member ("you are already a member of this organization"). | Nothing to do: the person is in. |
| `VALIDATION_FAILED` | 422 | `email` is not an email address of at most 320 characters; `workspaceIDs` names more than 100 workspaces or one that is not a live workspace of the organization; `role` is not a role; an invalid `limit` or `cursor`. | Correct the field named in `details.field`. |
| `RATE_LIMITED` | 429 | More than 50 invitations from one inviter, or 200 to one organization, in an hour. `Retry-After` and `details.retryAfterSeconds` say when the hour ends. | Wait, then send again. |
| `UNAVAILABLE`, reason `EMAIL_UNAVAILABLE` | 503 | Email cannot be sent right now. | Try again later. Nothing was stored. |

See [Errors](../reference/errors.md) for the shape of every error.

## Limits

| What | Value |
| --- | --- |
| How long an invitation lasts | 7 days from sending or resending |
| How often a link works | Once |
| Pending invitations per address and organization | 1 |
| Workspaces one invitation can name | 0 to 100 |
| Invited address | At most 320 characters |
| Invitations one person sends | 50 an hour, across all their organizations |
| Invitations one organization sends | 200 an hour, across all its inviters |
| How the hour is counted | From the first counted invitation; it does not slide and refused attempts do not extend it |
| Page size of the pending list | 1 to 100, default 50 |

## Questions and answers

**How do I invite someone?**
As an owner or admin, open **Settings > Organization > Members**, choose
"Invite member", enter their email address, choose a role and, for a member,
the workspaces.

**Can I invite someone who has no Talewright account?**
Yes. They create one from the invitation link, with the invited address.

**Can I invite several people at once?**
One address per invitation. Send one invitation for each person.

**How long is an invitation valid?**
7 days from the moment it was sent or resent.

**How do I resend an invitation?**
Invite the same address again. The person gets a new email with a new link,
and the earlier link stops working.

**The link says "Link expired or invalid". Why?**
It was already used, it is older than 7 days, a newer invitation replaced
it, it was revoked, the person who sent it left or lost the right to invite,
or the organization was deleted. Ask for a new invitation.

**I got two invitation emails. Which link do I use?**
The newest. Earlier links to the same organization no longer work.

**I am signed in with another address. What now?**
Choose "Sign in with another account" and sign in, or create an account,
with the address the invitation names.

**Can I accept with a different email address than the one invited?**
No. Ask to be invited at the address you want to use, or change your
account's email to the invited address first.

**Do I have to verify my email after accepting?**
No. Accepting the invitation verifies it.

**Can I change the role or workspaces of a pending invitation?**
Inviting the address again sets a new role and adds workspaces. To remove a
workspace, revoke the invitation and send a new one. Only an owner changes a
pending owner invitation this way.

**Can I see who has not accepted yet?**
Yes. Pending invitations are listed under "Invitations" on the Members page,
with their expiry.

**Is the invitee told when I revoke?**
No. Their link simply stops working.

**Am I told when someone accepts?**
No email is sent. They appear in the member list and leave the pending list.

**Can an admin invite an owner?**
No. Only owners invite owners. Admins can revoke an owner invitation.

**What happens to my invitations if I leave the organization?**
They are deleted and their links stop working. Someone else has to invite
those people again.

**Can someone else use my invitation link?**
They can see what it offers: the invited address, the organization, the
inviter and the role. They cannot accept it without an account for the
invited address.

**Why does it say "Too many invitations"?**
One person can send 50 invitations an hour, and one organization 200. The
message says when you can continue.

**Sign-up is closed. How does a new colleague get an account?**
Invite them. Starting from the invitation link, they can create an account
for the invited address.

**Does an invitation reserve the address or create an account?**
No. Nothing exists for the person until they create an account themselves.

**Can I invite someone to a workspace only, not to the organization?**
No. Everyone in a workspace is a member of the organization. Invite them as
"Member" and tick only that workspace: they then see only that workspace.

**Can an agent send or accept invitations?**
No. Invitations need a person signed in with a browser.

**Is the link safe to forward?**
Forwarding gives away the four preview details, nothing more. Still, treat
it as personal: whoever controls the invited inbox can join.

## Related pages

- [Members and roles](members-and-roles.md)
- [Workspaces](workspaces.md)
- [Organizations](organizations.md)
- [Deleting and restoring](delete-and-restore.md)
- [Sign-up and email verification](../accounts/sign-up.md)
- [Sign-in and sessions](../accounts/sign-in-and-sessions.md)
- [Roles and permissions](../reference/permissions.md)
- [Limits](../reference/limits.md) and [Errors](../reference/errors.md)
