> 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-user.md).

# Cybus::User

Create a user with your service and give it MQTT or HTTP access through roles or direct permissions.

The **Cybus::User** resource creates a user and optionally gives it initial permissions. You can grant permissions in the following ways:

* **Role-based access control**: Assign [roles](#roles) to the user. This is the recommended way, because it keeps permissions maintainable, especially in complex setups.
* **Direct permission assignment**: List [permissions](#permissions) for the user itself. Avoid this in complex setups, because it is harder to maintain.

## Username

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

The resource ID starts with a letter or a digit and contains only ASCII letters, digits, underscores (`_`), and periods (`.`). Hyphens (`-`) are not allowed. See [Resource ID Naming Requirements](https://docs.cybus.io/data-flows/service-commissioning-files/resources.md#resource-id-naming-requirements).

A username must have at least three characters.

## User Properties

| Property                    | Type       | Required |
| --------------------------- | ---------- | -------- |
| [password](#password)       | `string`   | Optional |
| [permissions](#permissions) | `object[]` | Optional |
| [roles](#roles)             | `string[]` | Optional |

### password

The password of the user. It must also meet the [password policy](https://docs.cybus.io/access/security/password-policy-configuration.md) of Connectware. Otherwise, Connectware does not create the user. The service still installs without it.

* **Optional**
* Type: `string`
  * Minimum length: 5 characters

### permissions

The permissions of the user. We recommend not using this property directly. Put the permissions into [Cybus::Role](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md) resources instead, and assign them with the [roles](#roles) property. This keeps permissions maintainable.

* **Optional**
* 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, either an MQTT topic or a REST API path. For the `mqtt` context, it can also be a Unified Namespace reference. See [Cybus::Role](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md#resource).

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

### roles

The [Cybus::Role](https://docs.cybus.io/data-flows/service-commissioning-files/resources/cybus-role.md) resources that hold the permissions of the user. This is the recommended way of granting permissions.

* **Optional**
* Type: `string[]`

Reference a role of the same service with `!ref`, as shown in the [example](#user-with-role-assignments-recommended). Without `!ref`, Connectware assigns a role only if the value is the full name of an existing role, such as `otherService.myRole`. Otherwise, the user does not get the role.

## Cybus::User Examples

### User with Direct Permissions

{% code lineNumbers="true" %}

```yaml
myUser:
  type: Cybus::User
  properties:
    password: 'somePassword1'
    permissions:
      - resource: userspace/werner/#
        operation: readWrite
        context: mqtt
```

{% endcode %}

### User with Role Assignments (Recommended)

{% code lineNumbers="true" %}

```yaml
# First define a role
operatorRole:
  type: Cybus::Role
  properties:
    permissions:
      - resource: userspace/data/#
        operation: read
        context: mqtt
      - resource: userspace/controls/#
        operation: readWrite
        context: mqtt

# Then assign the role to a user with !ref
productionUser:
  type: Cybus::User
  properties:
    password: 'securePassword123'
    roles:
      - !ref operatorRole
```

{% 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-user.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.
