IAM & Access Control
Configure roles, policies, permissions, and SSO/OIDC for your organization.
MechaMental provides a full RBAC (Role-Based Access Control) system for managing who can access what across your organization and workspaces. Access control is built around roles, policies, and permissions that you can customize to match your security requirements.
Permission Format
Every permission in MechaMental follows a structured format:
resource:scope:actionFor example:
apps:*:read-- read access to all appsendpoints:workspace-123:trigger-- trigger endpoints in a specific workspacesecrets:*:write-- write access to secrets in all scopesmodels:*:manage-- full management access to models
This format gives you fine-grained control over exactly what each role can do, down to individual resource types and scopes.
Built-in Roles
MechaMental ships with four built-in roles that cover the most common access patterns.
| Role | Description | Typical Use |
|---|---|---|
| Admin | Full access to all resources, settings, and organization-level configuration | Organization owners and platform engineers |
| Developer | Read/write access to apps, pipelines, tools, sources, and endpoints | Engineers building and configuring AI pipelines |
| Viewer | Read-only access to apps, dashboards, and analytics | Stakeholders and observers who need visibility |
| Operator | Can trigger endpoints, manage releases, and monitor executions, but cannot edit pipeline definitions | DevOps and operations staff responsible for deployments |
Built-in roles cannot be deleted
The four built-in roles are always available. You can create custom roles to supplement them, but you cannot modify or remove the defaults.
Custom Roles
When built-in roles do not fit your needs, create custom roles with precisely the permissions you require.
Navigate to Roles
Go to Admin -> IAM -> Roles in the sidebar. You will see the list of existing roles, including the four built-in ones.
Create a New Role
Click New Role. In the creation dialog, enter:
- Name -- a descriptive name (e.g., "QA Engineer", "Data Analyst")
- Description -- explain the purpose of this role
Assign Permissions
Select the permissions to include in this role. Permissions are grouped by resource type. For each resource, choose the actions to allow:
| Resource | Available Actions |
|---|---|
| Workspace | read, write, manage |
| Apps | read, write, manage, delete |
| Endpoints | read, write, trigger |
| Augmentations | read, write, execute |
| Secrets | read, write, delete |
| Models | read, write, manage |
| Tools | read, write, manage |
| Sources | read, write, delete |
| Analytics | view |
| Members | read, invite, remove |
Save and Assign
Click Save to create the role. You can then assign it to members from the Members tab.
Policies
Policies are the building blocks of access control. Each policy defines a granular rule that specifies:
- Effect --
allowordeny - Resource -- the resource type (apps, endpoints, tools, secrets, models, etc.)
- Scope -- all resources of a type, or a specific resource by ID
- Action -- the operation (read, write, manage, delete, trigger, execute)
Roles are composed of one or more policies. When a user attempts an action, MechaMental evaluates all policies attached to the user's role.
Deny always takes precedence
If a user has both an allow and deny policy for the same resource and action, the deny policy wins. Use deny policies sparingly for explicit restrictions -- for example, to prevent a specific role from accessing secrets while still allowing other operations.
Managing Members
Invite a Member
Navigate to Admin -> IAM -> Members and click Invite Member. Enter the user's email address and select the role to assign.
Accept Invitation
The invited user receives an email with a link to join the organization. Once they accept, they appear in the members list with their assigned role.
Change Roles
To change a member's role, click on the member in the list and select a new role from the dropdown. The change takes effect immediately.
Remove a Member
Click the member's overflow menu and select Remove. This revokes all access. Any API tokens they created are also invalidated.
SSO / OIDC Integration
MechaMental supports single sign-on through SAML and OpenID Connect (OIDC), allowing your team to authenticate using your existing identity provider.
Open Security Settings
Navigate to Admin -> Security in the sidebar.
Configure the Identity Provider
Select your SSO protocol (SAML or OIDC) and enter the provider details:
- Issuer URL -- your identity provider's OIDC discovery endpoint
- Client ID -- the OAuth client ID registered with your provider
- Client Secret -- the corresponding client secret
- Scopes -- typically
openid,profile,email - Redirect URI -- set this in your identity provider to
https://<your-instance>/auth/callback
- IdP Metadata URL -- your identity provider's SAML metadata endpoint
- Entity ID -- MechaMental's entity ID (auto-generated)
- ACS URL -- the Assertion Consumer Service URL (auto-generated)
- Certificate -- upload or paste your IdP's signing certificate
Test the Connection
Click Test Connection to verify that authentication works. MechaMental will initiate a login flow with your identity provider.
Enable SSO
Once verified, toggle Enable SSO to activate it for your organization. You can optionally enforce SSO, which disables password-based login.
Role Mapping
You can map identity provider groups to MechaMental roles. Users who belong to a specific IdP group are automatically assigned the corresponding role when they sign in.