# Adding a colleague, end to end

A colleague joins by being made a member of the workspace against the Google address they will sign in with. There is no invitation email and no pending state: a person is a member or is not. Their own first sign-in binds their identity, their session resolves to that workspace, and from then on every approval and every change is recorded against them individually.

- **Status:** Available
- **Audience:** both
- **Last verified:** 2026-09-10
- **Canonical:** https://connectbyjbrh.com/docs/workflows/adding-a-colleague/

## The flow, stage by stage

1. Trigger — somebody who administers the workspace decides another person needs access.
2. User or external event — none yet. The colleague does nothing until the membership exists.
3. Authentication and workspace resolution — the colleague signs in with their own Google account; their session resolves to the workspace their membership names, not to whoever added them.
4. Ingest — nothing is fetched. Adding a person changes no business data at all.
5. Canonical record — a membership row: one workspace, one platform person, a role and a status, unique for that pair. It is control-plane data, held outside every workspace's business records.
6. Reasoning — none. Access is a permission question, never a model question.
7. Knowledge, memory and rules — unchanged. A new colleague inherits the workspace's knowledge and rules rather than bringing their own.
8. Autonomy and approval — the workspace's autonomy is a property of the workspace, not of the person. A new member does not loosen or tighten it.
9. Action through a provider — the only provider is Google, and only to establish who the person is.
10. Result — the colleague opens the app and sees the same workspace as everyone else in it.
11. Relationship, timeline and memory — nothing. A colleague is a member of the workspace, never a contact inside it.
12. Audit, usage and Needs You — from the first action onwards, the log names the person who took it. Approvals stop being anonymous the moment there is more than one of you.

## What a membership carries

| Field | What it decides |
|---|---|
| Workspace | Which workspace this person's session resolves to |
| Person | The platform identity, which is the Google account they sign in with |
| Role | Whether they may configure the workspace or only work in it. Administration-level settings check for the administrator role explicitly and refuse anyone else with a clear message |
| Status | Only an active membership counts. An inactive one is not a member with fewer rights; it is not a member |

One person, one membership per workspace — the pair is unique, so adding somebody twice cannot produce two conflicting roles. Belonging to more than one workspace is normal; the session decides which one is active, and [You are in the wrong workspace](/docs/troubleshooting/wrong-workspace/) covers what to do when it is not the one you expected.

## What the colleague does

1. Open the app and continue with Google, using exactly the address the membership was created against.
   - Result: Their identity is bound on that first sign-in. A different address — a personal one, an alias — authenticates fine and belongs to nothing.
2. Look at Needs You before anything else.
   - Result: It is the fastest way to understand what the workspace is currently waiting on a human for, and it is the screen a second person is usually added to help with.
3. Take one held item through to a decision.
   - Result: The log now names them. Two people working a queue with no record of who released what is the situation the decision log exists to prevent.

> **Careful** Access is per person, never shared. Two people signing in as one account on one browser end each other's sessions and make the decision log useless — it can only record the account that acted.

## Removing somebody, and what survives

Removing a colleague ends their access to the workspace. It does not remove their history: the approvals they gave, the messages they released and the changes they made stay in the decision log, attributed to them. An audit that forgot people who left would be no audit at all.

Their sessions are the other half of the job. A membership that no longer exists stops resolving, so a session that outlives it cannot reach the workspace's data; where a departure is sensitive, ending sessions explicitly is the deliberate step rather than waiting for a lifetime to run out. [Sessions](/docs/account/sessions/) describes what a session actually holds.

## Questions

### Is there an invitation email?

No. There is no invitation record and no pending-invite state in the system — a person is a member of a workspace or is not. Tell your colleague their access is ready and which address to use; their first sign-in does the rest.

### Can two people work the approval queue at once?

Yes, and the log records who released what. The practical caution is staleness rather than collision: an item somebody else has just handled disappears from the queue, so refresh before assuming an empty queue means the work is done.

### Does a colleague need their own Google account?

Yes. Google sign-in is the only way in, membership is per person, and password sign-in is not available. Sharing one account defeats both the second factor and the record of who did what.

## Related

- [Workspace administration](https://connectbyjbrh.com/docs/account/workspace-admin/)
- [Who may change what](https://connectbyjbrh.com/docs/autonomy/permissions/)
- [Signing in for the first time, end to end](https://connectbyjbrh.com/docs/workflows/first-sign-in/)
- [Sessions](https://connectbyjbrh.com/docs/account/sessions/)
- [The decision log](https://connectbyjbrh.com/docs/autonomy/audit-trail/)
- [Inviting your team](https://connectbyjbrh.com/docs/getting-started/inviting-your-team/)

## What this page is based on

- `backend/app/models.py` — the workspace membership record and its uniqueness rule
- `backend/app/tenant_unified_ui.py` — the administrator-role check on configuration
- docs-source/sources/GENERAL.md sections 1-3 — control-plane tables and workspace resolution
- Connect capability registry (docs-source/facts.py)