Skip to main content
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.
A visible page or a role label is not authorization. The backend rechecks the exact permission and resource ownership for every protected operation.

​
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. 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:
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:
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. 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.

Administration overview

Understand personal, organization, and platform administration.

Security

Review tenant isolation, secrets, audit, sharing, and field encryption.
Last modified on August 9, 2026