Role

Defines a named set of permissions that can be assigned to accounts, groups, or tenants.

This object can be configured from the WebUI under Management › Directory › Roles

Fields

description

Type: String · required

Description of the role

memberTenantId

Type: Id<Tenant>?

Identifier for the tenant this role belongs to

roleIds

Type: Id<Role>[]

List of roles this role extends

enabledPermissions

Type: Permission[]

List of permissions that are explicitly enabled.

disabledPermissions

Type: Permission[]

List of permissions that are explicitly disabled, even if they would be inherited through other roles or groups. This takes precedence over enabled permissions.

JMAP API

The Role object is available via the urn:stalwart:jmap capability.

x:Role/get

This is a standard Foo/get method as defined in RFC 8620, Section 5.1.

This method requires the sysRoleGet permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Role/get",
          {
            "ids": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:Role/set

This is a standard Foo/set method as defined in RFC 8620, Section 5.3.

Supports create, update, and destroy operations in a single call.

Create

This operation requires the sysRoleCreate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Role/set",
          {
            "create": {
              "new1": {
                "description": "Example",
                "disabledPermissions": [],
                "enabledPermissions": [],
                "memberTenantId": "<Tenant id>",
                "roleIds": []
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Update

This operation requires the sysRoleUpdate permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Role/set",
          {
            "update": {
              "id1": {
                "description": "updated value"
              }
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

Destroy

This operation requires the sysRoleDestroy permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Role/set",
          {
            "destroy": [
              "id1"
            ]
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

x:Role/query

This is a standard Foo/query method as defined in RFC 8620, Section 5.5.

This method requires the sysRoleQuery permission.

curl -X POST https://mail.example.com/api \
  -H 'Authorization: Bearer $TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
      "methodCalls": [
        [
          "x:Role/query",
          {
            "filter": {
              "description": "example"
            }
          },
          "c1"
        ]
      ],
      "using": [
        "urn:ietf:params:jmap:core",
        "urn:stalwart:jmap"
      ]
    }'

The x:Role/query filter argument accepts the following conditions (combinable with AnyOf / AllOf / Not per RFC 8620):

Condition	Kind
description	text
memberTenantId	id of Tenant

CLI

stalwart-cli wraps the same JMAP calls. See the CLI reference for installation, authentication, and general usage.

Fetch

stalwart-cli get role id1

Create

stalwart-cli create role \
  --field description=Example \
  --field 'memberTenantId=<Tenant id>' \
  --field 'roleIds=[]' \
  --field 'enabledPermissions=[]' \
  --field 'disabledPermissions=[]'

Query

stalwart-cli query role
stalwart-cli query role --where description=example

Update

stalwart-cli update role id1 --field description='Updated'

Delete

stalwart-cli delete role --ids id1