Roles & Access Control

MITRITY uses a role-based access control (RBAC) system to govern what your team members can do within the platform. Every user is assigned a role that determines their permissions across agents, policies, tools, security features, credentials, and administrative functions.

The Four-Role Model

MITRITY has four roles, each with progressively broader permissions:

Role	Description	Typical User
Owner	Full control over the tenant, including billing, SAML configuration, and user management	Company founder, CTO, Head of Security
Manager	Can manage agents, policies, tools, and security features within their access scope	Engineering manager, Security lead, DevOps lead
Member	Can view and interact with day-to-day features (audit logs, approvals) but cannot modify configurations	Engineer, Analyst, Security analyst
Viewer	Read-only access to dashboards and reports	Executive, Auditor, Compliance officer

Permissions Matrix

The following table shows the complete permissions matrix. A checkmark indicates the role has permission for that action.

Agent Management

Action	Owner	Manager	Member	Viewer
View agents	Yes	Yes	Yes	Yes
Register agent	Yes	Yes	No	No
Update agent configuration	Yes	Yes	No	No
Deregister agent	Yes	Yes	No	No
View agent permissions	Yes	Yes	Yes	Yes
Modify agent permissions	Yes	Yes	No	No
View agent destinations	Yes	Yes	Yes	Yes
Modify agent destinations	Yes	Yes	No	No

Policy Management

Action	Owner	Manager	Member	Viewer
View policies	Yes	Yes	Yes	Yes
Create policy	Yes	Yes	No	No
Update policy	Yes	Yes	No	No
Delete policy	Yes	Yes	No	No
Run simulation	Yes	Yes	Yes	No
View simulation results	Yes	Yes	Yes	Yes

Approval Workflows

Action	Owner	Manager	Member	Viewer
View approval queue	Yes	Yes	Yes	Yes
Approve action	Yes	Yes (scoped)	No	No
Deny action	Yes	Yes (scoped)	No	No

Tool Catalog

Action	Owner	Manager	Member	Viewer
View tool catalog	Yes	Yes	Yes	Yes
Create custom tool	Yes	Yes	No	No
Update tool	Yes	Yes	No	No
Delete custom tool	Yes	Yes	No	No

Security Features

Action	Owner	Manager	Member	Viewer
View injection events	Yes	Yes	Yes	Yes
Mark false positive	Yes	Yes	Yes	No
View delegation chains	Yes	Yes	Yes	Yes
View DLP events	Yes	Yes	Yes	Yes
View threat intelligence	Yes	Yes	Yes	Yes
Configure threat intel settings	Yes	Yes	No	No
Submit threat indicator	Yes	Yes	Yes	No

Credential Broker

Action	Owner	Manager	Member	Viewer
View credential metadata	Yes	Yes	Yes	Yes
Create credential	Yes	Yes	No	No
Update credential	Yes	Yes	No	No
Delete credential	Yes	Yes	No	No
Create grant	Yes	Yes	No	No
Revoke grant	Yes	Yes	No	No
Revoke lease	Yes	Yes	No	No

Compliance & Reporting

Action	Owner	Manager	Member	Viewer
View ML insights	Yes	Yes	Yes	Yes
View audit log	Yes	Yes	Yes	Yes
Generate compliance report	Yes	Yes	Yes	No
Download report	Yes	Yes	Yes	Yes
Share report	Yes	Yes	No	No

Administration

Action	Owner	Manager	Member	Viewer
View users	Yes	Yes	Yes	No
Invite user	Yes	No	No	No
Update user role	Yes	No	No	No
Remove user	Yes	No	No	No
Reset user MFA	Yes	No	No	No
View environments	Yes	Yes	Yes	Yes
Create environment	Yes	No	No	No
Update environment	Yes	No	No	No
Delete environment	Yes	No	No	No
Configure SAML SSO	Yes	No	No	No
Manage API keys	Yes	Yes	No	No
View billing	Yes	No	No	No
Manage subscription	Yes	No	No	No
Configure settings	Yes	No	No	No

Access Scopes

Access scopes determine where a user's permissions apply. A Manager with "all" scope can manage agents across all environments. A Manager with "scoped" access can only manage agents in specific environments they have been granted access to.

Scope Types

Scope	Description	Available For
all	Tenant-wide access. The user's role permissions apply across all environments.	Owner (always), Manager (configurable)
scoped	Environment-specific access. The user's role permissions only apply within the environments they have been granted access to.	Manager (configurable), Member (configurable)

Scope Assignment

Owners always have all scope. Managers and Members can be assigned either all or scoped access.

curl -X PATCH https://api.mitrity.com/api/v1/users/user_jdoe \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "manager",
    "access_scope": "scoped",
    "environment_ids": ["env_staging", "env_development"]
  }'

Response:

{
  "data": {
    "id": "user_jdoe",
    "email": "jdoe@company.com",
    "name": "Jane Doe",
    "role": "manager",
    "access_scope": "scoped",
    "environments": [
      { "id": "env_staging", "name": "Staging" },
      { "id": "env_development", "name": "Development" }
    ],
    "mfa_enabled": true,
    "last_login": "2026-03-01T09:00:00Z",
    "created_at": "2026-02-15T10:00:00Z"
  },
  "meta": {
    "request_id": "req_user001",
    "timestamp": "2026-03-01T10:00:00Z"
  }
}

How Scoping Works

When a scoped Manager attempts an action:

1. The system checks the user's role permissions (can Managers do this action?).
2. The system checks the user's environment access (is this resource in an environment the user has access to?).
3. Both checks must pass for the action to proceed.

Example: A Manager scoped to "Staging" can create policies in the staging environment but cannot create policies that apply to the production environment.

Environment-Level Access

Environments are the primary scoping mechanism. When a user has scoped access, they can only interact with resources in their assigned environments.

Granting Environment Access

curl -X POST https://api.mitrity.com/api/v1/users/user_jdoe/environments \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "environment_id": "env_production"
  }'

Revoking Environment Access

curl -X DELETE https://api.mitrity.com/api/v1/users/user_jdoe/environments/env_production \
  -H "Authorization: Bearer mk_live_your-api-key"

Resource Grants

For even finer-grained access, you can grant users access to specific agents within their environments. This is useful when a team member should only manage a subset of agents, not all agents in an environment.

Creating a Resource Grant

curl -X POST https://api.mitrity.com/api/v1/users/user_jdoe/grants \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "agent",
    "resource_id": "agt_sales-bot",
    "permissions": ["view", "manage_permissions", "manage_destinations"]
  }'

Response:

{
  "data": {
    "id": "grant_8k2m",
    "user_id": "user_jdoe",
    "resource_type": "agent",
    "resource_id": "agt_sales-bot",
    "resource_name": "sales-bot",
    "permissions": ["view", "manage_permissions", "manage_destinations"],
    "created_at": "2026-03-01T10:05:00Z"
  },
  "meta": {
    "request_id": "req_grant001",
    "timestamp": "2026-03-01T10:05:00Z"
  }
}

Listing Resource Grants

curl https://api.mitrity.com/api/v1/users/user_jdoe/grants \
  -H "Authorization: Bearer mk_live_your-api-key"

Revoking a Resource Grant

curl -X DELETE https://api.mitrity.com/api/v1/users/user_jdoe/grants/grant_8k2m \
  -H "Authorization: Bearer mk_live_your-api-key"

User Management API

List Users

curl https://api.mitrity.com/api/v1/users \
  -H "Authorization: Bearer mk_live_your-api-key"

Response:

{
  "data": [
    {
      "id": "user_jsmith",
      "email": "jsmith@company.com",
      "name": "John Smith",
      "role": "owner",
      "access_scope": "all",
      "mfa_enabled": true,
      "last_login": "2026-03-01T08:00:00Z",
      "created_at": "2026-01-15T10:00:00Z"
    },
    {
      "id": "user_jdoe",
      "email": "jdoe@company.com",
      "name": "Jane Doe",
      "role": "manager",
      "access_scope": "scoped",
      "environments": [
        { "id": "env_staging", "name": "Staging" },
        { "id": "env_development", "name": "Development" }
      ],
      "mfa_enabled": true,
      "last_login": "2026-03-01T09:00:00Z",
      "created_at": "2026-02-15T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_user002",
    "timestamp": "2026-03-01T10:00:00Z",
    "total": 2
  }
}

Update User Role

curl -X PATCH https://api.mitrity.com/api/v1/users/user_jdoe \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "manager",
    "access_scope": "all"
  }'

Set User Access Scope

curl -X PATCH https://api.mitrity.com/api/v1/users/user_jdoe \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "access_scope": "scoped",
    "environment_ids": ["env_staging", "env_development", "env_production"]
  }'

Invite a New User

curl -X POST https://api.mitrity.com/api/v1/users/invite \
  -H "Authorization: Bearer mk_live_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "role": "member",
    "access_scope": "scoped",
    "environment_ids": ["env_development"]
  }'

The invited user receives an email with a link to set up their account and configure MFA.

Remove a User

curl -X DELETE https://api.mitrity.com/api/v1/users/user_jdoe \
  -H "Authorization: Bearer mk_live_your-api-key"

Removing a user revokes all their sessions, API keys, and resource grants immediately.

MFA Management

All MITRITY users are required to have MFA enabled. Owners can reset a user's MFA if they lose access to their MFA device.

Reset User MFA

curl -X POST https://api.mitrity.com/api/v1/users/user_jdoe/reset-mfa \
  -H "Authorization: Bearer mk_live_your-api-key"

After resetting, the user is prompted to configure a new MFA method on their next login.

Dashboard Management

User Management Page

Navigate to Settings > Team to manage users. The page displays:

• All users with their roles, access scopes, MFA status, and last login
• Pending invitations
• Environment access for scoped users

Role Change History

All role changes are logged in the audit log. Navigate to Audit Log and filter by event_type=user.role_changed to see the history.

Best Practices

Follow the Principle of Least Privilege

Assign the most restrictive role that allows the user to perform their duties. Most team members should be Members, not Managers.

Use Scoped Access for Large Teams

For organizations with multiple environments and teams, use scoped access to ensure team members can only modify resources in their area of responsibility.

Require MFA for All Users

MFA is mandatory in MITRITY and cannot be disabled. This is a deliberate security decision — governance platforms must be protected against account compromise.

Review Access Quarterly

Schedule quarterly access reviews. Remove users who no longer need access and adjust scopes for users whose responsibilities have changed.

Limit the Number of Owners

A tenant should have 2-3 Owners for redundancy, not more. Owners have unrestricted access including billing and SAML configuration.

Audit Role Changes

Monitor role change events in the audit log. Unexpected role escalations may indicate account compromise or unauthorized access.

Related Documentation

• Environments — Multi-environment management
• SAML SSO — Enterprise SSO configuration
• API Keys — Programmatic access management
• Approval Workflows — Approval permissions by role
• Credential Broker — Credential access by role