Invite Your Team

An invitation creates the person's principal in your company before they sign in, lands them on the roles you chose, and returns a token to hand over. The steps below cover the whole lifecycle: creating the invitation, delivering the token, tracking who has not accepted, and revoking one.

Before You Start

• The CLI installed and signed in — dots auth whoami should print your identity and company.
• Authority to manage members (access.members.manage). Owner and Admin both carry it.
• A decision about which roles the person should arrive with. If none of the built-in four fit, build one first — Define Permission Roles is that path.

1. See The Roles You Can Invite Onto

Invitations name roles by UUID or by exact name, so start by reading what exists:

dots access roles list

That gives you the workspace's roles, system and custom, with their ids and which of them are immutable system roles.

It does not tell you what the system roles can do. The listing returns an empty permission set for Owner, Admin, Editor, and Viewer, because their permissions are code baselines rather than stored rows. For the actual contents, read the catalog:

dots access catalog

That prints every permission atom and the baseline each system role carries. It is the one place those four roles' real contents are visible.

2. Send The Invitation

dots access invites create --email teammate@example.com --role Editor

--role is repeatable and required — an invitation must land on at least one role, and it can land on several:

dots access invites create \
  --email teammate@example.com \
  --role Editor \
  --role "Release Manager"

Inviting from the web app is the same operation with one difference: that dialog picks a single role. A multi-role invitation is a CLI or API operation today.

Creating the invite writes the person into your company immediately as a principal with an invited status. They hold their roles from that moment, but nothing they grant is reachable until the invitation is accepted and the principal becomes active — an invited principal is denied on every check.

3. Hand Over The Token — You Get One Chance

The command prints a notice to stderr and the raw token to stdout. It is shown once and is not recoverable: only a hash is stored, and no command will show it again. Put it where it is going before you close the terminal.

Two properties of that token decide how you deliver it:

It does not expire. There is no time-to-live on an invitation. A token you generated months ago still works. The only way to invalidate one is to revoke it, which is step 5. Treat the token like a credential, not like a link that will lapse on its own.

It is single-use. Acceptance is a one-shot operation: the first accept binds the account and clears the invite, and a replay of the same token finds nothing to accept.

To confirm a token is still good without consuming it — the check to run when someone says their link does not work — resolve it:

dots access invites resolve --token dots_invite_...

That returns the workspace name and the role the invitation lands on. It needs no authentication, which is what lets the invitee run it too. It deliberately says nothing distinguishing about an unknown, revoked, or already-accepted token; all three answer the same way, so the command cannot be used to probe your workspace.

4. Track Who Has Not Accepted

There is no invite listing. Pending invitations are visible as principals whose status is invited:

dots access principals list --kind human

That output is also where you get the id you need to revoke one.

5. Revoke An Invitation

dots access invites revoke <principal-id>

Revocation is a hard removal of the pending principal, so the token can never be accepted afterward and the role assignments go with it. It applies only to an invitation that is still outstanding — once someone has accepted, they are an active member, and you remove or suspend the principal instead:

dots access principals update <principal-id> --status suspended

Suspension denies every check immediately while keeping the principal and its history intact, which is usually what you want over deletion.

6. What The Invitee Does

Acceptance happens in the web app, not the CLI. The invitee opens the accept link, signs in or creates their account, and the platform binds that verified identity to the principal you created. There is deliberately no CLI accept command: accepting requires the invitee's own authenticated session, so it belongs where they are signing in.

Email delivery is best-effort — a mail failure never fails the invitation, precisely because you are holding a token you can deliver yourself.

7. Narrow What They Can Reach

Roles are workspace-wide. If someone should work in one Dotabase rather than the whole workspace, invite them onto a thin role and attach a grant:

dots access grants add --dotabase reading-list --subject principal:teammate@example.com --preset editor

Remember that authority is additive: a grant can only add. If a role already gives someone workspace-wide row editing, a narrow grant does not claw it back. Restriction comes from inviting onto a thinner role in the first place.

Confirm It Landed

dots access audit --limit 20

The ledger is append-only and newest-first, and records the invitation, the acceptance, and any revocation. Filter with --actor, --event, --target, --since, or --until when it gets busy.

Access and Tenancy explains how principals, roles, and grants resolve into a decision; Access is the map of the whole plane; Quickstart: Teams is the condensed version of this page for a brand-new workspace.