# Roles

The PORTOS system has a predefined list of [user rights](https://developers.portos.sk/user-rights). Role allows to combine multiple user rights. When assigning rights to the user, roles are used. The role is represented by [`Role`](https://developers.portos.sk/data-models#role) class. Roles can be freely managed using API routes described in this section.

For instance, a user possessing the "sale" role would be granted rights such as `ticketCreate`, `ticketUpdate`, and `ticketClose`. Roles can be used to group user rights based on areas of work or represent specific job positions like "cashier," "waiter," or "manager."

During product installation, the default roles setup is established, and it follows a more detailed approach, allowing precise role management, such as "sale", "stats", "storno," etc.

## API methods

## Get roles

<mark style="color:blue;">`GET`</mark> `http://{server-address}/roles`

Returns all roles that matches query parameters. Result is of type [`QueryResult<Role>`](https://developers.portos.sk/data-models#queryresult).

#### Query Parameters

| Name   | Type      | Description                                                                                                              |
| ------ | --------- | ------------------------------------------------------------------------------------------------------------------------ |
| name   | string    | Supports NData syntax.                                                                                                   |
| label  | string    | Supports NData syntax.                                                                                                   |
| $skip  | int       | Pagination property. Describing number of records to skip from beginning of result collection.                           |
| $take  | int       | Pagination property. Maximum count of items to be returned.                                                              |
| $sort  | string\[] | <p>Comma separated list of property names. Please see NData syntax.<br></p>                                              |
| $count | bool      | If set to `true`, response will not contain `items` collection. Use to get resource count, not the resources themselves. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK Successful response" %}

```javascript
{
    "items":
    [
        {
            "name": "admin",
            "label": "Administrátor",
            "description": "Administrátorské oprávnenie, umožňuje vykonávať všetky akcie v tých zariadeniach, pre ktoré ma umožnené prihlásenie",
            "rights":
            [
                "admin"
            ],
            "envNames":
            [
                "BackOffice",
                "CashRegister",
                "PDA",
                "Tool"
            ],
            "_v": 1
        },
        {
            "name": "articleCategories",
            "label": "Správa tovarových skupín",
            "description": "Umožňuje používateľovi vytvárať, upravovať a mazať tovarové skupiny",
            "rights":
            [
                "articleCategoryCreate",
                "articleCategoryUpdate",
                "articleCategoryDelete"
            ],
            "envNames":
            [
                "BackOffice"
            ],
            "_v": 1
        }
    ],
    "count": 2,
    "totalCount": 2
}
```

{% endtab %}
{% endtabs %}

## Get role by name

<mark style="color:blue;">`GET`</mark> `http://{server-address}/roles/{name}`

Result is of type [Role](https://developers.portos.sk/data-models#role).

#### Path Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| name<mark style="color:red;">\*</mark> | string | Unique role name. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK Resource found." %}

```javascript
{
    "name": "articleCategories",
    "label": "Správa tovarových skupín",
    "description": "Umožňuje používateľovi vytvárať, upravovať a mazať tovarové skupiny",
    "rights":
    [
        "articleCategoryCreate",
        "articleCategoryUpdate",
        "articleCategoryDelete"
    ],
    "envNames":
    [
        "BackOffice"
    ],
    "_v": 1
}
```

{% endtab %}

{% tab title="404: Not Found Role with given name is not found." %}

```javascript
{
    "title": "Zdroj nebol nájdený",
    "status": 404
}
```

{% endtab %}
{% endtabs %}

## Create role

<mark style="color:green;">`POST`</mark> `http://{server-address}/roles`

Creates new role. Result is of type [Role](https://developers.portos.sk/data-models#role).

**Required rights**

Authorized user must have `RoleCreate` [right ](https://developers.portos.sk/user-rights)assigned.

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

#### Request Body

| Name                                     | Type | Description          |
| ---------------------------------------- | ---- | -------------------- |
| (body)<mark style="color:red;">\*</mark> | Role | Role model to create |

{% tabs %}
{% tab title="201: Created Successfuly created." %}

```javascript
{
    "name": "articleCategories",
    "label": "Správa tovarových skupín",
    "description": "Umožňuje používateľovi vytvárať, upravovať a mazať tovarové skupiny",
    "rights":
    [
        "articleCategoryCreate",
        "articleCategoryUpdate",
        "articleCategoryDelete"
    ],
    "envNames":
    [
        "BackOffice"
    ],
    "_v": 1
}
```

{% endtab %}
{% endtabs %}

## Create or update role

<mark style="color:orange;">`PUT`</mark> `http://{server-address}/roles/{name}`

Updates existing or creates new role. Result is of type [Role](https://developers.portos.sk/data-models#role).

**Required rights**

Authorized user must have assigned `RoleCreate` or `RoleUpdate` [right](https://developers.portos.sk/user-rights).

#### Path Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| name<mark style="color:red;">\*</mark> | string | Unique role name. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

#### Request Body

| Name                                     | Type | Description                |
| ---------------------------------------- | ---- | -------------------------- |
| (body)<mark style="color:red;">\*</mark> | Role | Model to create or update. |

{% tabs %}
{% tab title="200: OK Successfuly created or updated." %}

```javascript
{
    "name": "articleCategories",
    "label": "Správa tovarových skupín",
    "description": "Umožňuje používateľovi vytvárať, upravovať a mazať tovarové skupiny",
    "rights":
    [
        "articleCategoryCreate",
        "articleCategoryUpdate",
        "articleCategoryDelete"
    ],
    "envNames":
    [
        "BackOffice"
    ],
    "_v": 2
}
```

{% endtab %}
{% endtabs %}

## Delete role by name

<mark style="color:red;">`DELETE`</mark> `http://{server-address}/roles/{name}`

**Required rights**

Authorized user must have `RoleDelete` [right ](https://developers.portos.sk/user-rights)assigned.

#### Path Parameters

| Name                                   | Type   | Description       |
| -------------------------------------- | ------ | ----------------- |
| name<mark style="color:red;">\*</mark> | string | Unique role name. |

#### Headers

| Name                                            | Type   | Description                                    |
| ----------------------------------------------- | ------ | ---------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | Authorization header with authorization token. |

{% tabs %}
{% tab title="200: OK Successfuly deleted." %}

```javascript
{
    "name": "articleCategories",
    "label": "Správa tovarových skupín",
    "description": "Umožňuje používateľovi vytvárať, upravovať a mazať tovarové skupiny",
    "rights":
    [
        "articleCategoryCreate",
        "articleCategoryUpdate",
        "articleCategoryDelete"
    ],
    "envNames":
    [
        "BackOffice"
    ],
    "_v": 1
}
```

{% endtab %}

{% tab title="404: Not Found Given resource was not found." %}

```javascript
{
    "title": "Zdroj nebol nájdený",
    "status": 404
}
```

{% endtab %}
{% endtabs %}