> For the complete documentation index, see [llms.txt](https://docs.cybus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md).

# Cybus::Role

Group MQTT and HTTP permissions into a role and assign it to the users of your services, so that each permission set lives in one place.

The **Cybus::Role** resource defines a reusable set of permissions that you can assign to one or more [Cybus::User](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-user.md) resources. This is the recommended way to manage permissions in Connectware, because it keeps permissions consistent and easier to maintain.

The [resource ID](https://docs.cybus.io/data-flows/service-commissioning-files/resources.md#resource-id) becomes the role name, with the [service ID](https://docs.cybus.io/data-flows/services/serviceid.md) and a period in front of it. For example, the resource `myRole` in the service `myService` creates the role `myService.myRole`.

See also [User Management](https://docs.cybus.io/access/user-management.md).

## Role Properties

| Property                    | Type       | Required     |
| --------------------------- | ---------- | ------------ |
| [permissions](#permissions) | `object[]` | **Required** |

### permissions

The permissions that every user with this role gets.

* **Required**
* Type: `object[]`

Each permission is an object with the following properties:

| Property                | Type     | Required     |
| ----------------------- | -------- | ------------ |
| [context](#context)     | `string` | **Required** |
| [operation](#operation) | `string` | **Required** |
| [resource](#resource)   | `string` | **Required** |

#### context

The context in which Connectware interprets `resource`, either as an MQTT topic or as a REST API path.

* **Required**
* Type: `enum`
  * Must be one of the following values: `mqtt` for MQTT topics, `http` for REST API paths

#### operation

The access operation that the permission allows on `resource`.

* **Required**
* Type: `enum`
  * Must be one of the following values: `read`, `write`, `readWrite`

#### resource

The resource path that the permission applies to.

* **Required**
* Type: `string`

The value can be one of the following:

* An MQTT topic, for example `edge.cybus/#`.
* A REST API path.
* For the `mqtt` context, a Unified Namespace reference:
  * `uns:<path>`, for example `uns:factory/hall1`, grants subscribe access to the namespace below that node. The `operation` must be `read`.
  * `asset:<id>`, for example `asset:pump01`, grants read access to the property topics and the `$meta` topic of the asset, whatever the `operation` is. With `write` or `readWrite`, it also grants that operation on the `/set` topic and read access on the `/res` topic of each [writable property](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-model.md#data).

Both Unified Namespace forms work only with `context: mqtt`. They also work in the permissions of a [Cybus::User](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-user.md). An `asset:` grant needs a mounted asset. If the asset has no writable properties, a `write` or `readWrite` grant gives read access only, and the installation returns a warning.

Connectware replaces these references with topic filters when you install the service. While the grant exists, the service that owns the asset or the namespace cannot remove what the grant names. See [Removing Nodes](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-namespace.md#removing-nodes) and [Topics of an Asset](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-asset.md#topics-of-an-asset).

## Example

{% code lineNumbers="true" %}

```yaml
myRole:
  type: Cybus::Role
  properties:
    permissions:
      - resource: edge.cybus/#
        operation: readWrite
        context: mqtt
```

{% endcode %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
