Docs / Administration / Roles & Access Control

Roles & Access Control

MITRITY decides what each person in your organization can do with two settings:

Their role (Owner, Manager, Member or Viewer) decides which actions they may take.
Their access scope decides what they see: everything in the organization, or only the agents granted to them and the environments they work in.

The API enforces both on every request, for dashboard sessions and API keys alike.

The Four-Role Model

Role	Description	Typical User
Owner	Full control of the organization, including its settings, SAML SSO, billing and removing users. An owner always sees everything.	CEO, CTO, Head of Security
Manager	Manages the team other than owners, approves and denies held actions, resolves reviews and findings, and deletes agents, policies and credentials.	Engineering manager, Security lead, DevOps lead
Member	Registers and configures agents, policies, tools, credentials, DLP patterns and API keys, and generates reports.	Engineer, Analyst, Security analyst
Viewer	Reads dashboards, the audit log and reports.	Executive, Auditor, Compliance officer

Permissions Matrix

The tables show what the API allows each role. A scoped user takes these actions only on what they can see, and a few actions on what belongs to the whole organization need full access; see Access Scope. The dashboard offers some actions to fewer roles than the API does: it shows credential management, connected platforms, anomaly-detection models and threat-intelligence settings to owners and managers only.

Agent Management

Action	Owner	Manager	Member	Viewer
View agents	Yes	Yes	Yes	Yes
Register an agent	Yes	Yes	Yes	No
Update an agent, regenerate its key or revoke it	Yes	Yes	Yes	No
Delete an agent	Yes	Yes	No	No
Designate a host-observer credential	Yes	Yes	No	No
Change an agent's lifecycle status	Yes	Yes, except to Approved	No	No
View tool permissions and destinations	Yes	Yes	Yes	Yes
Change tool permissions and destinations	Yes	Yes	Yes	No

Policy Management

Action	Owner	Manager	Member	Viewer
View policies	Yes	Yes	Yes	Yes
Create or update a policy and its rules	Yes	Yes	Yes	No
Delete a policy or a rule	Yes	Yes	No	No
Restore an earlier policy version	Yes	Yes	No	No
Create, change or delete DLP patterns and a policy's DLP bindings	Yes	Yes	Yes	No
Set or remove a policy's LLM budget	Yes	Yes	Yes	No

Approvals and Governance Reviews

Action	Owner	Manager	Member	Viewer
View approvals	Yes	Yes	Yes	Yes
Approve or deny a held action	Yes	Yes	No	No
Request a governance review	Yes	Yes	Yes	No
Resolve a governance review	Yes	Yes, unless it is assigned to the Owner role	No	No
Change the governance gate and templates	Yes	No	No	No

Tool Catalog

Action	Owner	Manager	Member	Viewer
View the tool catalog	Yes	Yes	Yes	Yes
Create or update a custom tool	Yes	Yes	Yes	No
Delete a custom tool	Yes	Yes	No	No

Security Features

Action	Owner	Manager	Member	Viewer
View injection events, delegation chains, threat intelligence and host-observer findings	Yes	Yes	Yes	Yes
Mark an injection event as a false positive	Yes	Yes	Yes	No
Change delegation-chain settings	Yes	Yes	Yes	No
Change threat-intelligence settings	Yes	Yes	Yes	No
Override or suppress a threat indicator	Yes	Yes	Yes	No
Resolve a host-observer finding	Yes	Yes	No	No
Create, change, run or delete a red-team campaign, and resolve its findings	Yes	Yes	No	No
Verify the audit trail and read its checkpoints	Yes	Yes	No	No

Credential Broker

Action	Owner	Manager	Member	Viewer
View credential metadata, grants and leases	Yes	Yes	Yes	Yes
Create or update a credential	Yes	Yes	Yes	No
Delete a credential	Yes	Yes	No	No
Grant a credential to an agent	Yes	Yes	Yes	No
Revoke a credential grant	Yes	Yes	No	No
Issue or revoke a lease	Yes	Yes	Yes	No

Compliance & Reporting

Action	Owner	Manager	Member	Viewer
View the audit log, ML insights, compliance frameworks, the risk register and AI policy statements	Yes	Yes	Yes	Yes
See changes to people, their access and API keys in the audit log	Yes	Yes	No	No
Generate a report	Yes	Yes	Yes	No
Download a report	Yes	Yes	Yes	Yes
Export a report bundle	Yes	Yes	Yes	No
Share a report, schedule reports or delete a report	Yes	Yes	No	No
Recompute compliance posture	Yes	Yes	Yes	No
Override a control or set its owner	Yes	Yes	No	No
Add or update a risk	Yes	Yes	Yes	No
Accept or remove a risk	Yes	Yes	No	No
Draft an AI policy statement	Yes	Yes	No	No
Publish, retire or delete an AI policy statement	Yes	No	No	No
Attest to a published AI policy statement	Yes	Yes	Yes	Yes

Administration

Action	Owner	Manager	Member	Viewer
View the team	Yes	Yes	Yes	Yes
Invite a user	Yes	Yes, not as Owner	No	No
Change a user's role	Yes	Yes, not an Owner's and not to Owner	No	No
Set a user's access scope, agent grants and environment access	Yes	Yes, not an Owner's access scope	No	No
Reset a user's MFA	Yes	Yes, not a Manager's or an Owner's	No	No
Remove a user	Yes	No	No	No
View environments	Yes	Yes	Yes	Yes
Create or update an environment	Yes	Yes	No	No
Delete an environment	Yes	No	No	No
Configure SAML SSO and the organization's settings	Yes	No	No	No
Configure notification channels	Yes	Yes	No	No
Manage SIEM destinations	Yes	Yes	No	No
Create, change or revoke API keys	Yes	Yes	Yes	No
Connect or remove a SaaS platform	Yes	Yes	Yes	No
Sync a SaaS platform or change its enforcement	Yes	Yes	Yes	No
View the plan and subscription	Yes	Yes	Yes	Yes
Change the plan or open the billing portal	Yes	No	No	No
Delete the organization	Yes	No	No	No

API Keys Bound to an Environment

An API key bound to an environment works in that environment only, and it never takes an action that only an Owner may take, even when an Owner created it. Every action in the Owner-only rows above answers 403 Forbidden to such a key, and so does the Owner's part of the shared ones: making someone an Owner, changing an Owner's role, profile, access or MFA, resetting a Manager's MFA, resolving a review assigned to Owners, and approving an agent directly. Below that line, a key created by an Owner does what a Manager's key could, in its environment. See API Keys.

Access Scope

Every user has an access scope, all or scoped:

Scope	What the user sees
`all`	Every agent and every environment in the organization.
`scoped`	Only the agents granted to them and the environments they have access to.

An owner is never scoped: owners see everything, whatever their access scope says. A manager, member or viewer can be scoped. New users start with all, except invitations sent by a scoped manager, which start scoped.

Agent Grants and Environment Access

A scoped user's view is made of two separate lists:

	Decides	Does not decide
Agent grants	Which agents the user sees, and with them the records about those agents	Which environments the user works in
Environment access	Which environments the user works in: the environments themselves and the policies in them, with their DLP bindings and budgets. The user registers agents and creates policies only there.	Which agents the user sees

The two lists are independent. Environment access on its own shows no agents, so grant the agents as well. A granted agent is visible even when the user has no access to its environment.

An agent a scoped user registers is granted to them at once, and so is an environment a scoped manager creates.

Example: to let a user look after the sales agents and the Staging policies, set their access scope to scoped, grant them the sales agents, and give them access to Staging.

What a Scoped User Sees

Area	What a scoped user sees
Agents	Only their granted agents, in every list and count. Any other agent answers `404 Not Found`, the answer an unknown agent gets, whether they read it or try to change it.
An agent's configuration	For a granted agent: its tool permissions and destinations, credential grants and leases, and the response actions of a connected platform.
Activity and oversight	Records about their granted agents only: the audit log and its summaries, approvals and the pending count, governance reviews, injection events, ML insights, host-observer events and findings, red-team campaigns that name only granted agents with those campaigns' runs, red-team findings, delegation chains whose agents are all granted, LLM usage, threat-intelligence matches and the findings of connected platforms. A record about no agent is not shown.
Notifications	A notification that names agents appears only when every agent it names is granted. A notification about the organization appears too, except the notice that an organization report is ready.
Reports	Only the AI assessments of their granted agents. Organization reports (every other report type) are not shown, and asking to generate or schedule one answers `403 Forbidden`.
Risk register	Organization-level risks appear for everyone. A risk about an agent appears only when the agent is granted, and a scoped user adds agent risks only for granted agents.
Inventories	The AI bill of materials and the model inventory list every entry. The agents named on an entry are the granted ones only; usage totals count the whole organization.
Environments	Only the environments they have access to, the policies in them, and those policies' DLP bindings and budgets. Any other environment or policy answers `404 Not Found`.
The same for everyone	The team, the tool catalog, DLP patterns, credential definitions, connected platforms, the threat indicator catalog, compliance frameworks, AI policy statements and organization-wide analytics totals.
Full access only	Some things belong to the whole organization and are for Owners and users whose access scope is `all`: organization reports, the organization's usage of governed actions, creating, changing or deleting a credential, and connecting, syncing or disconnecting a SaaS platform or changing its enforcement. A scoped user gets `403 Forbidden` for them. Granting or leasing a credential to a granted agent, and the response actions on a granted agent of a connected platform, stay open to them.

The role still decides what a scoped user may do with what they see. A scoped manager approves only the held actions of their granted agents; a scoped member edits only their granted agents and the policies of their environments.

Setting Access Scope

Owners and managers set a user's access scope, agent grants and environment access, in Settings > Team or through the API. A manager cannot change an owner's access scope.

In Settings > Team, the button next to every other user who is not an owner shows their current access. While it reads Full Access, selecting it scopes the user. While it reads Scoped Access, selecting it opens the agents and environments granted to them, where you grant or revoke them, or switch the user back to full access. You can scope a pending invitation before it is accepted.

Through the API:

curl -X PUT https://api.mitrity.com/api/v1/users/user_jdoe/access-scope \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "access_scope": "scoped"
  }'

Response: the updated user:

{
  "id": "user_jdoe",
  "tenant_id": "tnt_4f9a",
  "email": "jdoe@company.com",
  "display_name": "Jane Doe",
  "role": "manager",
  "access_scope": "scoped",
  "mfa_method": "totp",
  "mfa_enrolled": true,
  "onboarding_completed": true,
  "auth_provider": "password",
  "status": "active",
  "last_login_at": "2026-03-01T09:00:00Z",
  "created_at": "2026-02-15T10:00:00Z",
  "updated_at": "2026-03-01T10:00:00Z"
}

access_scope is all or scoped; any other value is refused with 400.
A manager whose own access is scoped can scope other users but cannot set anyone to all, themselves included (403). They grant only the agents they see and the environments they have access to, and in another user's grants and environment access they see and revoke only those.
Setting a user back to all removes their agent grants. Their environment access is kept, and applies again if they are scoped later.
An invitation sent by a manager whose own access is scoped starts scoped, with nothing granted; the manager then grants what they see.
Changes take effect on the user's next request.
An API key acts with the current role and access scope of the user who created it.

Agent Grants

Owners and managers grant a scoped user one agent per request.

Creating an Agent Grant

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

resource_type is agent. An agent the caller cannot see answers 404 Not Found.

Response (201 Created):

{
  "id": "grant_8k2m",
  "user_id": "user_jdoe",
  "tenant_id": "tnt_4f9a",
  "resource_type": "agent",
  "resource_id": "agt_sales-bot",
  "created_at": "2026-03-01T10:05:00Z"
}

Listing Agent Grants

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

The response lists the user's grants under grants, each in the shape above. Owners, managers and the user themselves can read a user's grants.

Revoking an Agent Grant

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

Environment Access

Owners and managers give a scoped user access to one environment per request.

Granting Environment Access

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

An environment the caller has no access to answers 404 Not Found.

Response (201 Created):

{
  "id": "acc_3k9m",
  "user_id": "user_jdoe",
  "tenant_id": "tnt_4f9a",
  "environment_id": "env_production",
  "environment_name": "",
  "environment_slug": "",
  "created_at": "2026-03-01T10:05:00Z"
}

Listing Environment Access

curl https://api.mitrity.com/api/v1/users/user_jdoe/environment-access \
  -H "Authorization: Bearer mk_your-api-key"

The response lists the entries under environment_access, in the shape above, with environment_name and environment_slug filled in. Owners, managers and the user themselves can read a user's environment access.

Revoking Environment Access

Revoke by the entry's id, not the environment's:

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

User Management API

List Users

Every role can list the team.

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

Response:

{
  "data": [
    {
      "id": "user_jsmith",
      "tenant_id": "tnt_4f9a",
      "email": "jsmith@company.com",
      "display_name": "John Smith",
      "role": "owner",
      "access_scope": "all",
      "mfa_method": "totp",
      "mfa_enrolled": true,
      "onboarding_completed": true,
      "auth_provider": "google",
      "status": "active",
      "last_login_at": "2026-03-01T08:00:00Z",
      "created_at": "2026-01-15T10:00:00Z",
      "updated_at": "2026-02-01T10:00:00Z"
    },
    {
      "id": "user_jdoe",
      "tenant_id": "tnt_4f9a",
      "email": "jdoe@company.com",
      "display_name": "Jane Doe",
      "role": "manager",
      "access_scope": "scoped",
      "mfa_method": "totp",
      "mfa_enrolled": true,
      "onboarding_completed": true,
      "auth_provider": "password",
      "status": "active",
      "last_login_at": "2026-03-01T09:00:00Z",
      "created_at": "2026-02-15T10:00:00Z",
      "updated_at": "2026-03-01T10:00:00Z"
    }
  ],
  "total": 2,
  "limit": 50,
  "offset": 0
}

limit (default 50, max 200), offset and search page and filter the list. An invited user who has not signed in yet has status pending.

Update User Role

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

The same request updates display_name; send only the fields to change. Owners and Managers change roles; Managers cannot change an Owner's role or make anyone an Owner. The last Owner cannot be demoted (409 Conflict): make someone else an Owner first. When two Owners demote or remove each other at the same moment, one change goes through and the other is refused, so the organization always keeps an Owner. Members and Viewers change only their own display name. A role change applies on the user's next request. Access scope has its own request; see Setting Access Scope.

Invite a New User

Invitations are made on the tenant. Your tenant's ID is the tenant.id that GET /api/v1/tenants returns.

curl -X POST https://api.mitrity.com/api/v1/tenants/tnt_4f9a/invite \
  -H "Authorization: Bearer mk_your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@company.com",
    "role": "member"
  }'

Response (202 Accepted):

{
  "user_id": "user_n3w8",
  "tenant_id": "tnt_4f9a",
  "email": "newuser@company.com",
  "role": "member",
  "message": "invitation created; email delivery is pending"
}

Owners and Managers invite; Managers cannot invite an Owner, and the plan's user limit applies. The invited user receives an email with a link to set up their account and configure MFA. The new user starts with access scope all, unless the invitation comes from a manager whose own access is scoped: then it starts scoped, with nothing granted. To scope the new user, set their access scope, agent grants and environment access; you can do this before they accept.

Remove a User

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

Only Owners remove users, and not with an API key bound to an environment (403 Forbidden). An Owner cannot remove themselves, and the last Owner cannot be removed (400 Bad Request). Removing a user deletes their account, their API keys, their agent grants and their environment access at once. The compliance reports they generated stay, without their name. If their sign-in account cannot be deleted, or the removal meets another change to the organization's users or environments at the same moment, nothing is removed (409 Conflict) and you can try again.

MFA Management

All MITRITY users are required to have MFA enabled. Owners and Managers can reset a user's MFA if they lose access to their MFA device; resetting a Manager's or an Owner's takes an Owner.

Reset User MFA

curl -X POST https://api.mitrity.com/api/v1/users/user_jdoe/reset-mfa \
  -H "Authorization: Bearer mk_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:

Every user with their role, and pending invitations
For users you manage: their role and access, MFA reset, and removal if you are an Owner
For a scoped user: the agents granted to them and the environments they have access to

Role Change History

Every change to who may do what is recorded on your organization's audit trail as a governance change:

Event	Written when	Also records
`user.role_changed`	A user's role changes. A change of display name alone writes nothing.	The old and the new role
`user.access_scope.changed`	A user's access scope changes	The old and the new access scope
`user.invitation.created`	Someone is invited, to the platform or to the Academy	The address, the role and the access scope
`user.invitation.accepted`	An invitation is taken	The address, the role and the access scope
`user.invitation.revoked`	A pending invitation is removed	The address and the role
`user.removed`	A user is removed, by someone else or by deleting their own account	The address and the role
`user.mfa.reset`	An Owner or Manager resets a user's MFA, or a user resets their own	Whether it was their own
`access.agent.granted`, `access.agent.revoked`	An agent grant is added or removed, including the grant a scoped user receives on an agent they register	The agent
`access.environment.granted`, `access.environment.revoked`	Environment access is added or removed, including the access a scoped Manager receives on an environment they create	The environment

Each entry names the person who made the change and the person it is about, and the API key it was made with, if any. No invitation token is ever recorded.

In the dashboard, open Audit Log and choose the source Governance Changes. Through the API, filter by source and event type:

curl "https://api.mitrity.com/api/v1/audit?source=control_plane&event_type=user.role_changed" \
  -H "Authorization: Bearer mk_your-api-key"

These entries name people by email address and role, so only Owners and Managers see them. Members and Viewers, Academy learners included, see the rest of the audit log without them: the entries are left out of the list, its total and the audit summaries, and opening one by ID answers 404 Not Found. Reports never include them. The entries stay on the audit trail: verifying the trail covers them, and a SIEM destination receives them.

A scoped Manager sees the grant entries for the agents granted to them, and no entry about a person or an environment.

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 several teams, scope each person to their team's agents: grant them those agents, and give them access to the environments whose policies they maintain.

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

Review the Governance Changes in the audit log regularly. Look for a user.role_changed to Manager or Owner that nobody expected, a user.access_scope.changed to all, or grants to people who should not hold them: any of these may indicate account compromise or unauthorized access.

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