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

# Identity & access

> Database-backed permissions, roles, users, service accounts, invitations, SSO, and cross-workspace access.

MoleSignal authorizes actions with capability keys, not display-role comparisons. A user can belong
to several organizations and receive different permissions in each one.

## How authorization works

For an authenticated request, MoleSignal resolves:

1. the subject: user, service account, or API token;
2. the active organization or protected platform scope;
3. role assignments and explicit IAM bindings;
4. resource relationships and approved cross-organization grants;
5. required license features;
6. the permission required by the route and target resource.

The runtime permission catalog, built-in role mappings, and permission bundles are stored in
PostgreSQL. `GET /api/v1/iam/capabilities` returns the effective snapshot used by the web
application.

<Warning>
  A visible page or a role label is not authorization. The backend rechecks the exact permission
  and resource ownership for every protected operation.
</Warning>

## Permission scopes

Organization permissions cover one workspace. Examples include:

* `org.settings.read` and `org.settings.manage`;
* `org.members.read` and `org.members.manage`;
* `iam.roles.read`, `iam.roles.manage`, `iam.policies.read`, and `iam.policies.manage`;
* granular stream, dashboard, alert, schedule, saved-view, pipeline, function, report, audit, and
  Agent permissions.

Platform permissions begin with `sys.` and apply only in the `_sys` scope. Platform permissions control global
organizations, license versions, system telemetry, trace debugging, platform administrators, and
platform settings.

## Roles and permission bundles

Built-in organization roles are Owner, Admin, Editor, and Viewer. Platform Administrator is a
separate platform role. Built-in roles are maintained by the permission catalog and cannot be
edited.

Create custom roles when a person needs a narrower responsibility. The UI offers bundles such as
read-only observer, data analyst, pipeline developer, alert administrator, and organization
administrator as starting points. Review the final permission list before saving.

| Operation                    | Endpoint                    | Permission         |
| ---------------------------- | --------------------------- | ------------------ |
| List roles                   | `GET /api/v1/roles`         | `iam.roles.read`   |
| Create a custom role         | `POST /api/v1/roles`        | `iam.roles.manage` |
| Update a custom role         | `PATCH /api/v1/roles/{id}`  | `iam.roles.manage` |
| Delete an unused custom role | `DELETE /api/v1/roles/{id}` | `iam.roles.manage` |

A role that is still referenced by a membership, token, invitation, or binding cannot be deleted.

## Users, approvals, and invitations

Open **IAM → Users** to inspect organization members. If self-service signup requires approval, use
**IAM → Approvals** to approve or reject pending accounts.

Use **IAM → Invitations** to invite an email address with an initial role. Resend or revoke
a pending invitation. Email-domain policy applies to invitations and self-service or SSO
provisioning.

Common membership permissions are:

* `org.members.read` for listing members;
* `org.members.manage` for creating, approving, disabling, changing, or removing members.

Switching workspaces issues a newly scoped JWT. Organization ids and slugs are stable; changing the
display name does not change either identifier.

## Groups and teams

Groups organize identities for policy assignment. Teams organize people for product workflows such
as alert schedules and escalation targets. Every direct team member must belong to the same
organization.

Use role bindings and relationship policy when access should follow a group, team, resource, or
specific subject instead of changing a broad built-in role.

## Service accounts and API tokens

Use **IAM → Service accounts** for agents, CI, collectors, and integrations. Assign only the role or
permissions needed for that workload.

API tokens use this form:

```text theme={null}
ms_<prefix>_<secret>
```

The prefix is used for lookup and the secret is hashed at rest. The complete token is returned only
once. Send the token in the same header as a login JWT:

```http theme={null}
Authorization: Bearer ms_…
```

`api_tokens.read` lists token metadata and `api_tokens.manage` creates or revokes tokens.

## Cross-workspace access

An explicit grant can relate a subject in one organization to a resource in another. The server
checks that relationship and the resource permission together; a grant never turns the target
organization into the subject's active workspace.

For dashboards and reports, use the dedicated [resource sharing model](/en-US/resource-sharing).
Public shares receive a constrained share session, not organization membership.

## Single sign-on

Open **IAM → SSO** to configure OIDC or SAML 2.0 providers. Provider configuration is stored in the
database and takes effect without a process restart.

Configure discovery or protocol endpoints, client credentials or IdP certificate material, a
default role, and optional IdP-group mappings. New identities can be provisioned into the
provider's organization after email-domain and signup policy checks.

SSO requires the `sso` license feature. Provider management also requires organization settings
permissions.

## Platform administration

The `_sys` scope is isolated from organization IAM. Tenant JWTs and `ms_*` tokens cannot enumerate
system telemetry, license history, or platform administrators. Use a system-scoped session with
the required `sys.*` permission.

<CardGroup cols={2}>
  <Card title="Administration overview" icon="shield" href="/en-US/administration">
    Understand personal, organization, and platform administration.
  </Card>

  <Card title="Security" icon="lock" href="/en-US/security">
    Review tenant isolation, secrets, audit, sharing, and field encryption.
  </Card>
</CardGroup>