> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oasm.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Permissions & Access Control

> Understand permission groups and how to control what members can view and change in OASM workspaces

Access control in OASM is role-based: every [member](/members) of a [workspace](/workspace) is assigned a **permission group** — a named set of permissions — that determines exactly what they can see and change. Permissions are grouped so each member can only see and change what their role allows.

The permission model is enforced for user sessions, so every action a member takes in the Console is checked against their group. Automated access works through the workspace [API key](/api-keys), which is workspace-scoped and carries its own access model. This page explains the built-in groups and how to build and assign your own.

## Key concepts

### Permission group

A permission group is a named bundle of permissions. OASM ships with three built-in groups — **Owner**, **Admin**, and **Read only** — and you can create custom groups for any recurring team role. Assigning a group to a member grants exactly the permissions the group contains.

### Viewing vs. changing

Every capability has two levels: **viewing** (seeing data) and **changing** (modifying it). A member who can change something can always view it as well — you never need to grant the view half of a pair explicitly. This keeps groups compact and prevents broken setups where someone can modify what they cannot see.

### All permissions

The **Owner** group holds every permission, current and future. Owners never lose access when new capabilities ship.

## Built-in permission groups

<Table>
  | Group         | What members can do                                                                                                                         |
  | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
  | **Owner**     | Everything — including deleting the workspace and managing every other group                                                                |
  | **Admin**     | The everyday management surface: workspace settings, the workspace API key, members, invitations, workflows, permission groups, and targets |
  | **Read only** | View the workspace — including pending invitations and assets — without changing anything                                                   |
</Table>

The **Admin** group covers the everyday management surface — workspace settings and configuration, the workspace API key, members, invitations, workflows, permission groups, and targets. The **Read only** group grants the minimum needed to see pending invitations and inspect assets.

## The Permissions screen

The **Settings → Members** page has three tabs; the **Permissions** tab is where groups live:

<Steps>
  <Step title="Open Settings → Members">
    Navigate to the Members section of your workspace.
  </Step>

  <Step title="Open the Permissions tab">
    The tab lists existing permission groups with their assigned permissions.
  </Step>

  <Step title="Inspect a group">
    Select a group to open its detail page, where you can review or change its permissions.
  </Step>
</Steps>

## Create a custom permission group

<Steps>
  <Step title="Open the Permissions tab">
    Navigate to **Settings → Members → Permissions**.
  </Step>

  <Step title="Click Create group">
    The **Create group** button opens the group editor.
  </Step>

  <Step title="Name the group">
    Give the group a name that matches the role it serves, such as "Vulnerability Analyst" or "Scan Operators".
  </Step>

  <Step title="Select permissions">
    Choose the permissions the group grants. Remember: a member who can change something can also view it.
  </Step>

  <Step title="Save the group">
    Submit the form. The group is now available when assigning members or sending invitations.
  </Step>
</Steps>

## Assign a group to a member

<Steps>
  <Step title="Open the Members tab">
    Navigate to **Settings → Members → Members**.
  </Step>

  <Step title="Find the member">
    The tab shows a table of **Member** and **Permission** columns, so you can see each member's current group at a glance.
  </Step>

  <Step title="Change the permission">
    Use the member's row menu to change their permission group. The new group takes effect for that member's session immediately.
  </Step>
</Steps>

## Invite a member with a group

<Steps>
  <Step title="Click Invite member">
    On the **Members** tab, the **Invite member** button opens the invitation form.
  </Step>

  <Step title="Enter email addresses">
    Provide the email address(es) of the people you want to invite.
  </Step>

  <Step title="Choose a permission group">
    Select the group the invitees should receive when they accept.
  </Step>

  <Step title="Send the invitation">
    Submit the form. The invitation appears under the **Invitations** tab with **EMAIL**, **EXPIRES**, **STATUS**, and **PERMISSION GROUPS** columns until it is accepted or expires.
  </Step>
</Steps>

<Info>
  **Invitation management is itself permissioned.** Creating, resending, and cancelling invitations requires the right permission — only members whose group allows it can do these actions.
</Info>

## Recommended permission matrix

<Table>
  | Capability                     | Owner | Admin | Read only |
  | ------------------------------ | :---: | :---: | :-------: |
  | All permissions                |   ✅   |   —   |     —     |
  | Manage workspace settings      |   ✅   |   ✅   |     —     |
  | Delete the workspace           |   ✅   |   ✅   |     —     |
  | Manage the workspace API key   |   ✅   |   ✅   |     —     |
  | Manage members and invitations |   ✅   |   ✅   |     —     |
  | Manage workflows               |   ✅   |   ✅   |     —     |
  | Manage permission groups       |   ✅   |   ✅   |     —     |
  | Manage targets                 |   ✅   |   ✅   |     —     |
  | View assets                    |   ✅   |   ✅   |     ✅     |
  | View pending invitations       |   ✅   |   ✅   |     ✅     |
  | View the audit log             |   ✅   |   ✅   |     —     |
</Table>

## How permissions are enforced

Permission groups are enforced for **user sessions**. When a member performs an action in the Console, the platform checks the action against the member's group and denies it when the corresponding permission is missing. Because groups are evaluated per action, changing a member's group takes effect immediately — you do not need to wait for a session to expire.

Enforcement is not limited to UI actions. The same checks apply wherever the permission model is consulted, so a member cannot bypass a restriction through other channels. Automated access is a separate surface: the workspace [API key](/api-keys) is workspace-scoped with its own access model, so key-based callers are governed by that model rather than by member groups.

Every permission-relevant action is recorded in the [Audit log](/audit-log). Audit events capture the **actor** — a user, an API key, or an agent — which lets you trace exactly who (or what) changed a permission, invited a member, or modified a workspace.

<Danger>
  **Owner is permanent authority.** An Owner can delete the workspace, rotate the API key, and read or modify every resource — including permission groups themselves. Grant Owner membership only to the smallest set of trusted people, and audit the group regularly.
</Danger>

## Best practices

* **Start with least privilege.** Assign the smallest group that lets a member do their job, and escalate only when a concrete need appears. The **Read only** group exists precisely for members who only need to monitor results.
* **Escalate through groups, not ad hoc grants.** If a member needs more access, create or assign a purpose-built group instead of granting individual permissions one by one — each extra permission expands what they can change.
* **Reserve Owner for a minimal set.** Owner covers every current and future permission. Keep Owner membership to a small, trusted set and use **Admin** for day-to-day administration.
* **Audit access continuously.** Permission changes, membership changes, and API activity are recorded in the [Audit log](/audit-log). Review it regularly — audit events record the actor (a user, an API key, or an agent), so you can trace who changed what.
* **Model roles as groups, not ad hoc grants.** Recurring team roles should be custom groups with descriptive names, so the permission matrix stays reviewable.
* **Separate user and API access.** User access is governed by permission groups enforced on sessions; programmatic access uses the workspace [API key](/api-keys), which is workspace-scoped with its own access model. Review both surfaces, not just member groups.

## Related

<Card icon="users" title="Members" horizontal href="/members">
  Invite members, manage invitations, and change permission groups
</Card>

<Card icon="shield-user" title="Users and roles" horizontal href="/users-and-role">
  Understand platform-level roles such as admin, user, and bot
</Card>

<Card icon="key" title="API keys" horizontal href="/api-keys">
  Manage the workspace API key and its access model
</Card>

<Card icon="scroll-text" title="Audit log" horizontal href="/audit-log">
  Review who changed what, and with which actor
</Card>