Map jobs to roles
Start from what people do, then pick the narrowest role that covers it. See the permission reference for what each role holds.
Grant a role to a team through an
access grant rather than to each person, and access follows team
membership.
Let people in through single sign-on
- Connect the identity provider of the company under Identity & Access → SSO providers, and map its groups to roles with External group → role. Roles then follow the directory at every sign-in.
- Set a Default role of Viewer for people who match no group.
- Add the company email domains, so invitations and single sign-on accept only those addresses.
- Turn off self-service joining, or keep it with Require admin approval.
[auth].root_email, is the platform administrator and signs in with a
password. Keep that password in a vault, and use the account only when single sign-on is not available.
Give access to one thing, for a while
Some needs are narrow and temporary: a contractor who reads one dashboard, an analyst who queries one stream. Create an access grant on that resource with an Expires at, instead of a role for the whole workspace. An Environment constraint, such asstaging, limits the grant further to the requests of that environment.
For people of another organization, a
cross-organization share gives access to
chosen dashboards or streams once an administrator of that organization accepts it. It applies only to
the resources and the organization chosen, and is never passed on.
Use teams for ownership
Teams are more than groups of people: on-call schedules and escalation steps, fallback routes, and the team chats, knowledge, skills, and MCP servers of Mole Agent all refer to them. Create one team per group that owns services and answers pages, and keep the membership current when people move.Give programs their own identity
One service account per integration: when an integration is retired, disable its account, and every token
of it stops. Set an expiry on every token that a person creates, and never give a login session to a
program.
Review access regularly
Every quarter, and when someone leaves:- In Users, disable people who left and check Last active for accounts that are no longer used.
- In API tokens, revoke tokens that were not used lately or that belong to people who left.
- In Access grants, remove expired needs.
- In Audit, look at changes of roles, grants, tokens, and settings.
- Check the sharing policy and the public links that exist.
Acceptance criteria
- Most people hold Viewer, and every Admin and Owner is a deliberate choice.
- People sign in through SSO, with roles that follow directory groups.
- Every program uses a service account or an intake token, never a person’s session.
- No API token is older than its expiry policy, and unused tokens are revoked.
- A quarterly review has a date, an owner, and a record in the audit trail.