# Invite members and assign roles

## Purpose
Get another person into your account and give them exactly the access they need, no
more.

## Who this is for
Account administrators. You need a role carrying account-member or account-role
permissions; if you cannot see **Team & Access** in the sidebar, you do not have them.

## Before you start
- Know the person's email address.
- Decide their role *and its scope*. A role is always granted against something: the
  whole account, one campaign, one assessment, or one participant. "Auditor for the
  2026 pilot" is a role at campaign scope, not an account-wide role.
- Members are not participants. If you want someone to *answer* an assessment, see
  [Add people to a campaign](/operate/tenant-admin/add-people-to-a-campaign) instead.

## Invite someone who is not in the account yet

1. Open **Team & Access** in the sidebar.
2. Go to the **Member invitations** tab and choose **Invite member**.
3. Fill in first name, last name and email address, and set **Invitation valid for
   (days)** if the default of seven is wrong for this wave: an out-of-range number is
   refused before the invitation is sent.
4. Under **Initial Role**, pick one role. The button stays disabled until you do.
5. Choose **Send Invitation**.

The invitation appears in the **Member invitations** tab, and an email goes out with a
link to `/auth/entry?token=…`. Invitations expire; the expiry date is stated in the
email. From the same tab you can resend or revoke an invitation that has not been
accepted.

### Resending, and why the second press often sends nothing

Pressing **Resend** twice in quick succession does not put two identical emails in
somebody's inbox. The second press is refused as a duplicate: you get a message saying
so, naming the moment an identical send would be allowed again: ten minutes after the
first, for an invitation.

Nothing is lost when that happens, and one detail is worth knowing: a refused resend
does **not** rotate the invitation's link. That matters because an ordinary resend
does: it mints a fresh token and the previous email's link stops working. So a
duplicate press leaves the invitee holding a link that still works, and the activation
link shown on screen is that same live link, ready to pass on by hand.

A resend can also report that nothing was sent for a different reason: the address is
on the suppression list (it has hard-bounced, the recipient reported a message as spam,
or somebody unsubscribed). That refusal is permanent until an administrator removes the
listing, and the on-screen message says which of the two happened.

### Resending in bulk: read the rows, not just the toast

Select several invitations and choose **Resend invites** and the toolbar reports what
the whole batch did: how many went out, how many were held back as duplicates, how
many addresses are suppressed, and how many were refused outright. The rows themselves
carry the detail: each invitation you just resent gains a small label under its status
saying what happened to *it*, with the same sentence you would see on the invitation
on its own.

That distinction is worth acting on. A duplicate is a wait: the person already has a
working link in their inbox, and pressing again inside the window changes nothing. A
suppression is a dead end: no email will reach that address until a platform
administrator removes the listing, so your next move is to pass the activation link on
some other way (**Copy invite link** on the row).

The batch always finishes. A row the server refuses does not stop the rows after it;
it gets its own receipt like any other.

Two things to know about this dialog:

- An invitation grants exactly **one** role, so the role list is single-select. Assign
  further roles once the person has joined.
- The name you type is stored on the invitation and applied to their member record when
  they accept, unless they already have a name on file, which always wins.

Avatars are not set here. They come from the person's BIMei profile, or from their own
**Profile & Preferences** page once they are in, which is reached by clicking their own
name at the foot of the sidebar, not from a sidebar entry.

## Add someone who already has an identity

Use this when the person already exists in the system and you just want to attach them
to this account.

1. **Team & Access → Members list**, then **Add member** at the right of the toolbar
   under the filters.
2. Keep the **Existing User** tab.
3. Type their user id or email. The field suggests known principals as you type, but it
   accepts any value you type, so check it.
4. Tick one or more roles under **Assign Roles** (required; the New User tab calls the
   same field **Role to Grant**).
5. Optionally add comma-separated labels.
6. Choose **Add Member**.

The **New User** tab of this same dialog sends an *email invitation*, exactly as
**Invite member** does: same single role, same stored name. Use whichever you reach
first.

## Change what an existing member can do

1. **Team & Access → Members list**.
2. Select the members you want to change and use **Assign roles**, or open a single
   member's actions and inspect their current assignments. (The Member assignments tab's
   own toolbar button is the singular **Assign role**, same dialog.)
3. In the assignment dialog, pick the roles and the scope to grant them at.

To take access away, go to **Member assignments** and revoke the specific assignment.
Revoking an assignment removes the access it granted; it does not remove the person from
the account.

## Build a role that does not exist yet

System roles are locked and cannot be edited. To get a variation:

1. **Team & Access → Member roles**.
2. Open the row's **⋮** menu and choose **Duplicate role** on the closest system role.
   Do not use **New role**: saving one reports *Role not found* (see the limit below).
3. Attach the policies the role should carry, then save.
4. Assign the new role as above.

Roles and policies can also be exported to JSON and imported back, useful for copying a
permission design between accounts.

## What happens next
- The member appears in the **Members list** with a status of **Pending** until they
  accept, then **Active**.
- Every grant and revoke is written to the account's audit trail (see
  [Read the activity log](/operate/tenant-admin/activity-log-and-csv-export)).
- The sidebar a member sees is built from what they can actually do, so a
  campaign-scoped auditor will not see **Roles & Policies** or **Access** at all.

## Pre-fill an invitee's organisation and labels

A campaign invitation can carry the organisation the person works for and the labels
their roster row should have, so the row they land on when they accept already says both
instead of waiting for somebody to edit it afterwards. It is what makes inviting one
municipality's twelve staff one action rather than thirteen.

There is no field for this on the invite dialog yet. It is set through the v1 API, on
`POST /api/v1/accounts/{accountId}/invitations`, as `organisationName` and `labels`,
either for the whole request or on an individual recipient, who overrides it. The labels
are chips in the form `department:public_works`, which
[the import's label-group columns](/operate/tenant-admin/add-people-to-a-campaign) describe.

Two rules apply when the invitation is accepted:

- **The organisation is resolved then, not when you invite.** The name is matched against
  your account's organisations at the moment the person activates, so somebody who never
  accepts leaves no organisation behind.
- **Nothing already on the roster row is overwritten.** If the programme pre-loaded that
  person with an organisation, the invitation's does not replace it: an existing link
  was put there deliberately. Labels are merged onto whatever the row already carries.

## Limits and gotchas
- The **Members list** filter bar filters on what the list actually holds: the **Role**,
  **Campaign** and **Label** dropdowns are populated from the members on screen, so a
  dropdown with nothing to offer stays empty, and **Label** is disabled when no member
  carries one. **Status** is the exception: a fixed four-value list, not derived from
  the rows.
- **New role does not work.** The editor mints an id the save path does not recognise as
  a new role, so it is sent as an edit of a role that does not exist and comes back
  *Role not found*. **Duplicate role** on the nearest system role is the supported way
  to start a custom role, and it is what the roles guide documents.
- Sign-in itself is handled by BIMei, not by Assessor.io. You invite people here; they
  authenticate there.

## Related pages
- [Add people to a campaign](/operate/tenant-admin/add-people-to-a-campaign)
- [Read the activity log and export it](/operate/tenant-admin/activity-log-and-csv-export)
- [Glossary](/build/reference/GLOSSARY)
