For AI agents: a documentation index is available at https://docs.coverbase.com/llms.txt. This page is also available in markdown by appending .md to the URL.
This guide is part of the User Guides collection. It is for admins who decide who can see and change what. If you are setting up a new environment, do this after Admin and setup step 1, once your team is invited.
Custom roles are a gated feature. Configuration → Organization → Roles always shows what each role can do, but if it shows a read-only table instead of the editor described below, custom roles have not been switched on for your organization yet, or your own role cannot edit organization settings. Ask your Coverbase contact. The six default roles work either way.
The six default roles
Every member holds exactly one role. These six ship with the product and cannot be edited, but you can clone any of them as a starting point.
Start with Member for anyone on the risk team and Admin for the one or two people who own the program. Reach for a custom role only when a real job does not fit.
Service Account is the role your API keys use. Every key your organization issues authenticates as it, so editing that role changes what your integrations can do. One rule to know: a service account can request a change to supplier bank details but cannot approve one. Approving stays with a person.
How a permission is built
Every permission in Coverbase is three things joined together.Resource
The thing being acted on. Vendors, assessments, findings, contracts, controls, API keys and the rest, grouped in the editor into Vendor risk, Controls and detection, Workflow and intake, and Administration.
Action
What you are doing to it: read, create, update, export, assign, approve, comment, archive, or run.
Scope
How much it covers: every record in the organization, or only the records that person is assigned to.
vendor, the action update, and the scope all records. “A Siloed Member can update the vendors they own” is the same resource and action at a narrower scope.
Not every combination exists. Some resources have no per-record assignment, so scope does not apply to them: there is no such thing as being assigned to an API key or to organization settings. Those are always organization-wide, and the editor shows them that way.
Finding the role editor
Go to Configuration → Organization → Roles. The Roles list on the left shows every role in your organization and how many permissions it holds, with a Default role badge on the six that ship with the product. Selecting one opens it on three tabs: Permissions (the matrix), Members, and Activity. Default roles are read-only. To base a new role on one, open it and choose Clone. A custom role you no longer need can be archived with Archive; tick Show archived under the list to see archived roles again.Reading the permission matrix
The matrix has one row per resource and one column per action, and the legend above it names each value. Each cell holds one of four values.
A cell with a red ! is a Conflict with hierarchy: a combination the rules below do not allow.
Resources sit in four collapsible groups, each showing how many of its permissions are granted. Set all on a group switches every cell in it to Off, Assigned or Org at once.
Click a cell to cycle it through off, assigned only, and org-wide. Right-click to pick No access, Assigned only or All records directly. Use Filter by resource or action to narrow a large matrix while you work, and Show to switch between All rows, only the Granted ones, and only your unsaved Changes.
Assigned scope is not available everywhere. A resource with no assignment model only offers all records or no access, and the cell says so when you hover it.
What counts as assigned
Each resource has one rule for what “assigned to me” means, and that rule is the same for every action. Assigned only on read and Assigned only on update cover the same records. The matrix then decides which actions the person can take on them.
Holding a role through a user group counts the same as being named on the record. Watching a vendor, service or contract does not make it assigned to you: watchers get updates, not access.
Vendors and their services
A vendor’s Relationship Owners and Risk Analysts reach every service of that vendor. They see the services on the vendor’s Services tab and, if their role has Assigned only update on services, they can edit them. It does not work the other way. A Relationship Owner of one service sees that service and its vendor, but not the vendor’s other services. To move a service to a different vendor with assigned scope, that vendor must also be assigned to you. Creating, archiving and merging services always need org-wide permissions.The rules the editor enforces
Some combinations describe a role the product cannot deliver. The editor catches those before you save, shows them in a banner above the matrix, and offers Fix all.An action needs the matching read
An action needs the matching read
You cannot give someone update, approve, assign, archive, export, comment or run on a resource without also giving them read at the same scope. Editing a record you cannot open is not a narrower permission, it is a broken screen.The fix is to raise read to the scope the other action needs.
Vendor-backed resources need vendor read
Vendor-backed resources need vendor read
Assessments, findings, commitments, services and Radar alerts are all reached through a vendor. Granting one of them without vendor read produces a page the person cannot open. The editor requires vendor read alongside any of these.
Create without read is a warning, not an error
Create without read is a warning, not an error
A role that can create records but not read them is unusual, and the banner says so, but it saves. It is a real pattern for an intake submitter or a write-only integration that files records it never lists.
You cannot grant what you do not hold
You cannot grant what you do not hold
If your own role does not include a permission, you cannot give it to another role. Admins hold everything, so this never limits them. It matters when you delegate role management to someone who is not an Admin: they can build roles up to their own level of access, and no further.To create a role broader than your own, ask an Admin to do it.
You cannot lock yourself out
You cannot lock yourself out
Editing the role you yourself hold, you cannot remove its ability to read and manage roles. Doing so would leave you unable to reopen the editor and undo it. Another Admin can still change your role for you.
Building a custom role
1
Start from the closest default
Open the default role nearest to what you want and choose Clone, or choose + beside Roles (New role) to start from nothing. Cloning is usually faster, and it starts you from a set that already passes the rules above.
2
Name it for the job, not the person
“Contract reviewer” outlasts “Priya’s role”. Names show up in the member list and in the audit trail.
3
Set the matrix
Work resource by resource. For each one, decide read scope first, then the actions on top of it. Filtering by resource keeps you out of the rest of the matrix while you do it.
4
Clear the banner
Fix anything the validation banner reports. Fix all resolves each issue in the direction you were heading: where the resource still has some read access, it raises read to the scope the other permission needs; where read is off entirely, it removes the permission that depended on it.
5
Save, then add members
A new role’s first save is Create role; after that the button reads Save with a count of your changes. Members can only be added to a saved role, so save first, then use the Members tab.
Assigning people to a role
The Members tab on a role shows everyone who holds it. Add someone with Add to role, and remove them with Remove from role. You can also change a person’s role from the Role column on Configuration → Organization → Members (People on the redesigned settings). Two things are blocked:- The last Admin cannot be demoted or removed. Make someone else an Admin first. This applies whether you are removing them from the Admin role or assigning them a different one.
- Changing your own role asks for confirmation. If the change removes your own administrative access, you lose it immediately, and only another Admin can give it back.
What custom roles do not restrict
A few areas are visible and actionable for every member regardless of role. They are listed in the editor under Not restricted by custom roles so you are not left looking for a toggle that does not exist.
Some surfaces have no toggles of their own because they follow the records they act on. Email, engagements, Coverbase AI and Radar signals inherit the permissions of whatever they are acting on.
Configuration pages follow the permission for the thing they configure. Clause sets follow contract permissions. The risk scale and Document Insights settings follow organization settings.
Seeing what changed
Every role carries its own activity log, on its Activity tab. It records who changed the role and what they changed, so a permission that appeared or disappeared can be traced to a person and a time. A newly created role has no activity until it is saved. Role changes also appear in the organization-wide audit trail alongside everything else. See Audit trails.Read roles from MCP or the API
You can read roles and their permissions from an MCP client withquery_platform(kind="roles"), or with GET /v1/roles on the Platform configuration API. Both need role:read:org, which organization API keys hold.
Building, editing and assigning roles stays in the dashboard. Neither MCP nor the API changes a role.
Troubleshooting
Related
Admin and setup
The full setup sequence. Roles come after inviting your team.
Audit trails
Every recorded event, including role and membership changes.
API keys
Service accounts and scoped keys for integrations.
MCP permissions
How the same permissions apply when an AI assistant acts on your data.