> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Organize access for teams and programs

> Match roles to jobs, sign people in through single sign-on, use teams for ownership, give programs an identity of their own, and review access regularly.

Access grows by exception: someone needs one more permission today, a contractor needs a dashboard, a
script needs a token. Without a plan, a year later nobody knows who can delete a stream or which token
still writes data. Decide the model once, and let the exceptions fit into it.

## Map jobs to roles

Start from what people do, then pick the narrowest role that covers it. See the
[permission reference](https://docs.molesignal.com/en-US/identity/roles.md#permission-reference) for what each role holds.

| Job | Role | Note |
| - | - | - |
| Reads dashboards, logs, and incidents | **Viewer** | The default for most people. Viewers also chat with Mole Agent. |
| Builds dashboards, alert rules, and pipelines; answers pages | **Editor** | Editors acknowledge and silence incidents, but cannot change members, tokens, or settings. |
| Runs the workspace: members, roles, tokens, settings, synthetic checks, status pages | **Admin** | A few people per workspace. |
| Owns the instance | **Owner** | Every Owner also reaches the platform `_sys` organization. Keep two or three, no more. |
| A job that no built-in role fits, such as an alert administrator, or an Editor who also runs synthetic checks | A [custom role](https://docs.molesignal.com/en-US/identity/roles.md#roles) | Start from the closest **Permission template**, then add or remove permissions. |

Grant a role to a [team](https://docs.molesignal.com/en-US/identity/teams.md#teams) through an
[access grant](https://docs.molesignal.com/en-US/identity/roles.md#access-grants) rather than to each person, and access follows team
membership.

## Let people in through single sign-on

1. Connect the identity provider of the company under
   [Identity & Access → SSO providers](https://docs.molesignal.com/en-US/identity/sso.md), and map its groups to roles with
   **External group → role**. Roles then follow the directory at every sign-in.
2. Set a **Default role** of **Viewer** for people who match no group.
3. Add the company [email domains](https://docs.molesignal.com/en-US/identity/sso.md#email-domains), so invitations and single sign-on
   accept only those addresses.
4. Turn off [self-service joining](https://docs.molesignal.com/en-US/settings/organization.md#registration-and-access), or keep it with
   **Require admin approval**.

The root user, the account of `[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](https://docs.molesignal.com/en-US/identity/roles.md#access-grants) on that resource with an
**Expires at**, instead of a role for the whole workspace. An **Environment** constraint, such as
`staging`, limits the grant further to the requests of that environment.

For people of another organization, a
[cross-organization share](https://docs.molesignal.com/en-US/identity/roles.md#share-resources-across-organizations) 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](https://docs.molesignal.com/en-US/alerting/on-call.md) and escalation steps,
[fallback routes](https://docs.molesignal.com/en-US/notification-channels#configure-fallback-routes), and the team chats,
knowledge, skills, and MCP servers of [Mole Agent](https://docs.molesignal.com/en-US/agent#organization-team-and-personal-resources)
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

| Program | Credential |
| - | - |
| A collector or agent that only sends data | The default intake token, write only. |
| Browser or mobile code | The RUM client token of the application, which end users can see. |
| CI that reports deployments | The default intake token, which can also report deployments. |
| Automation that reads data or changes resources | A [service account](https://docs.molesignal.com/en-US/identity/tokens.md#service-accounts) with a narrow custom role. |
| A person running scripts or an MCP client | A personal API token with an expiry. |

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](https://docs.molesignal.com/en-US/identity/members.md#users), disable people who left and check **Last active** for
  accounts that are no longer used.
* In [API tokens](https://docs.molesignal.com/en-US/identity/tokens.md#create-an-api-token), revoke tokens that were not used lately or
  that belong to people who left.
* In [Access grants](https://docs.molesignal.com/en-US/identity/roles.md#access-grants), remove expired needs.
* In [Audit](https://docs.molesignal.com/en-US/settings/data-security.md#audit), look at changes of roles, grants, tokens, and settings.
* Check the [sharing policy](https://docs.molesignal.com/en-US/settings/organization.md#sharing-and-public-access) and the public links
  that exist.

Set the [audit retention](https://docs.molesignal.com/en-US/settings/platform.md#audit-retention) to what compliance requires.

## 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.

## Related guides

* [Identity & access](https://docs.molesignal.com/en-US/identity)
* [Roles and access grants](https://docs.molesignal.com/en-US/identity/roles.md)
* [API tokens and service accounts](https://docs.molesignal.com/en-US/identity/tokens.md)
* [Security and multi-tenancy](https://docs.molesignal.com/en-US/security.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.