# Roles and permissions (/docs/reference/roles-permissions)



This catalogue helps tenant administrators and security reviewers choose roles and understand exactly what an operation permission allows. It covers **185 permission identifiers** in **14 families**, including **142 selectable in custom tenant roles** and **nine built-in functional roles**.

Use the docs search for an exact identifier such as `mcp.server.create`, a role such as Data Builder, or a family such as Tenant. Each permission has a linkable entry with its meaning, scope, built-in grants, custom-role eligibility and implied permissions.

<Cards>
  <Card title="System roles and baseline access" href="/docs/reference/roles-permissions/system-roles" />

  <Card title="Tenant administration guide" href="/docs/administration/tenant-settings" />
</Cards>

## Permission families [#permission-families]

<Cards>
  <Card title="API credentials" href="/docs/reference/roles-permissions/credential" description="4 permissions · 4 custom-role selectable" />

  <Card title="Agents" href="/docs/reference/roles-permissions/agent" description="6 permissions · 6 custom-role selectable" />

  <Card title="Authorization" href="/docs/reference/roles-permissions/authorization" description="5 permissions · 2 custom-role selectable" />

  <Card title="Chat" href="/docs/reference/roles-permissions/chat" description="7 permissions · 7 custom-role selectable" />

  <Card title="Data Hub" href="/docs/reference/roles-permissions/data" description="25 permissions · 25 custom-role selectable" />

  <Card title="Deep Research" href="/docs/reference/roles-permissions/research" description="6 permissions · 6 custom-role selectable" />

  <Card title="Document processing" href="/docs/reference/roles-permissions/document" description="4 permissions · 4 custom-role selectable" />

  <Card title="Storage" href="/docs/reference/roles-permissions/storage" description="11 permissions · 11 custom-role selectable" />

  <Card title="MCP" href="/docs/reference/roles-permissions/mcp" description="9 permissions · 8 custom-role selectable" />

  <Card title="MLflow" href="/docs/reference/roles-permissions/mlflow" description="30 permissions · 21 custom-role selectable" />

  <Card title="Platform" href="/docs/reference/roles-permissions/platform" description="18 permissions · 0 custom-role selectable" />

  <Card title="Skills" href="/docs/reference/roles-permissions/skill" description="5 permissions · 0 custom-role selectable" />

  <Card title="Spark" href="/docs/reference/roles-permissions/spark" description="9 permissions · 9 custom-role selectable" />

  <Card title="Tenant" href="/docs/reference/roles-permissions/tenant" description="46 permissions · 39 custom-role selectable" />
</Cards>

## How access is decided [#how-access-is-decided]

A permission names an operation, such as `data.ingestion.run`. A role bundles permissions. A resource relationship determines whether a caller may perform that operation on a particular object.

For tenant-scoped operations, access combines:

1. **Current tenant membership.** A role assignment does not create membership.
2. **Operation permission.** This can come from baseline membership, an applicable administrator assignment, a functional system role or a custom role, including group-inherited assignments.
3. **Resource and request checks.** Ownership, sharing, workspace or namespace access, tenant boundaries and endpoint-specific prerequisites still apply.

For example: Data Builder → `data.ingestion.run` → invoker access on the ingestion → required source and destination access. The functional role alone does not authorize every ingestion in the tenant.

Platform-administration permissions apply at installation scope and are not granted through tenant custom roles. Shared catalogue permissions with a `platform.` prefix are explicitly marked as tenant-scoped in their entries.

## Read a permission entry [#read-a-permission-entry]

| Field        | Meaning                                                                                            |
| ------------ | -------------------------------------------------------------------------------------------------- |
| Scope        | Where the operation permission is evaluated: platform or selected tenant                           |
| Granted by   | Baseline membership, an administrator assignment, or the functional roles that supply this gate    |
| Custom role  | Whether the exact identifier can be selected in a custom tenant role; excluded entries explain why |
| Also implies | Other catalogue permissions derived from this grant, including transitive implications             |

“Baseline member” includes users with any of the nine system roles. “Yes” under custom role does not mean the permission is absent from baseline access. The catalogue is additive, not a deny-policy system.

Write implications are specific, not wildcard rules. For example, `mcp.server.delete` implies update, list and read. It does not imply server creation. An implication does not bypass an independent resource check.

The catalogue describes permission semantics, not a promise of a separate endpoint or portal control for every identifier. Entries that represent model authority without a dedicated operation say so. Use your deployment's BSQAI API reference for the available routes.

## Define a custom role [#define-a-custom-role]

Custom roles belong to one tenant and can be assigned to eligible tenant users or ordinary groups. They cannot grant platform administration, tenant-administrator status or resource ownership. They do not remove baseline access or access supplied by other roles.

For an MCP configuration editor, a minimal role definition is:

```json
{
  "name": "MCP configuration editor",
  "description": "Update existing tenant MCP server registrations.",
  "permission_ids": ["mcp.server.update"]
}
```

This adds update authority, with list/read implied. It does not grant server creation or deletion. Current members already have the baseline server-use gate. Resource credentials remain personal.

Creating this role requires `tenant.role.create`; assigning it requires `tenant.role.assign`. Changes to custom roles synchronize asynchronously. A `202` response means the change was accepted, not that access or revocation has already taken effect. Updates and assignment changes to an existing custom role require its current `expected_version`; stale versions return `409`.

## Inspect your deployment [#inspect-your-deployment]

Authenticate to the BSQAI API and select the tenant as described in [Access and tenant context](/docs/use/api#tenant-selection). Reading the following endpoints requires `tenant.role.list`:

| Endpoint                             | Returns                                                                                                                  |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `GET /v1/authz/permission-catalogue` | Permissions selectable in custom roles, descriptions, categories and selectable implied permissions                      |
| `GET /v1/authz/roles?kind=system`    | System-role additions above baseline and direct assignments in `roles`; membership permissions in `baseline_permissions` |
| `GET /v1/authz/roles?kind=custom`    | Custom roles and direct assignments in `roles`; the same `baseline_permissions` list                                     |
| `GET /v1/authz/roles/{role_id}`      | One system role by assignment ID, or one custom role by UUID                                                             |

`GET /v1/authz/roles` without a filter returns both role kinds and the same baseline list. `baseline_permissions` describes tenant membership, not the caller's effective access, and is not an assignable role. Resource ownership and sharing checks still apply.

The live permission-catalogue endpoint reports permissions selectable in custom roles for your deployment, rather than the full reference shown here. Listing a role or permission does not grant it. These pages describe the 1.4.0 catalogue; compare with the deployed API when reviewing a different version.

## Related pages [#related-pages]

* [System roles and baseline access](/docs/reference/roles-permissions/system-roles)
* [Tenant settings](/docs/administration/tenant-settings)
* [Security model](/docs/foundation/security-model)
* [Multi-tenancy and tiered RBAC](/docs/data/multi-tenancy-and-tiered-rbac)