[Intum](https://intum.fr/aide.md) / [Konto](https://intum.fr/aide/konto.md)

# [Role](https://intum.fr/aide/konto/role.md) | [API](#api)

## Role i uprawnienia

System ról kontroluje, do jakich funkcji i danych mają dostęp użytkownicy w ramach konta.

## Domyślne role

### Właściciel

Pełny dostęp do wszystkich funkcji systemu, w tym:
- Zarządzanie hasłami użytkowników
- Dostęp do prywatnych skrzynek mailowych wszystkich użytkowników
- Zarządzanie widgetami WebChat
- Wszystkie uprawnienia administracyjne

### Administrator

Uprawnienia administracyjne:
- Zarządzanie użytkownikami i ich rolami
- Konfiguracja konta i domen
- Zarządzanie skrzynkami i folderami
- Przeglądanie i cofanie aktywności
- Dostęp do rozliczeń i raportów
- Zarządzanie rolami i grupami
- Zatwierdzanie urlopów
- Moderacja komentarzy w bazie wiedzy

### Użytkownik

Standardowy dostęp do:
- Profilu i dashboardu
- Wszystkich włączonych modułów (zadania, mail, CRM, formularze, baza wiedzy itd.)
- Przeglądania aktywności
- Komentowania zadań

### Gość

Ograniczony dostęp:
- Tylko profil
- Wymaga zatwierdzenia przez administratora (moderacja)

## Role własne

Można tworzyć **role niestandardowe** z dowolną kombinacją uprawnień. Rola niestandardowa pozwala precyzyjnie określić, do których modułów i funkcji użytkownik ma dostęp.

Uprawnienia są podzielone na:
- **Modułowe** - dostęp do modułów (Organize, Mail, CRM, Formularze, Baza wiedzy itd.)
- **Operacyjne** - tworzenie, edycja, usuwanie w danym module
- **Funkcyjne** - dostęp do konkretnych funkcji (aktywności, użytkownicy, domeny, rozliczenia, API tokeny, webhooki)

Przy tworzeniu roli nie można przypisać uprawnień wyższych niż własna rola.

### Dziedziczenie ról (bazowanie na innej roli)

Rola własna może **bazować na innej roli** - systemowej lub innej roli własnej. Wtedy automatycznie dziedziczy wszystkie jej uprawnienia, a administrator tylko dodaje kolejne.

Przykład: tworzysz rolę "Handlowiec" bazującą na roli Użytkownik i dodajesz uprawnienie do Insight. Handlowiec ma wtedy wszystko co Użytkownik plus Insight - bez potrzeby ręcznego zaznaczania każdego checkboxa.

Dziedziczenie działa kaskadowo - rola może bazować na innej roli własnej, która z kolei bazuje na systemowej.

### Uprawnienia własne (custom privileges)

Oprócz uprawnień systemowych (dostęp do modułów, zarządzanie użytkownikami itd.) rola może mieć **uprawnienia własne** - dowolne nazwy definiowane przez administratora.

Uprawnienia własne służą do kontrolowania dostępu do rzeczy, które nie mają odpowiednika w systemowych uprawnieniach, np.:
- Dostęp do konkretnej aplikacji Noe
- Możliwość eksportowania raportów
- Uprawnienie specyficzne dla procesu w firmie

Wpisuje się je jako listę nazw oddzielonych przecinkami lub spacjami.

Dobra praktyka: używaj kropki w nazwach (np. `app.crm`, `report.export`, `custom.invoices`). Dzięki temu od razu widać że to uprawnienie własne, a nie systemowe, i nie będzie kolizji nazw gdyby w przyszłości pojawiło się systemowe uprawnienie o takiej samej nazwie.

Jeśli nazwa uprawnienia własnego pokrywa się z nazwą systemowego uprawnienia, systemowe ma zawsze priorytet - uprawnienia własne działają tylko dla nazw, które nie istnieją w systemie.

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

## API - Role

### Lista ról

```
GET /account/roles.json
```

### Pobranie roli

```
GET /account/roles/:id.json
```

### Tworzenie roli

```
POST /account/roles.json
```

**Parametry:**

- `role[name]` - nazwa roli
- `role[privileges][]` - tablica uprawnień systemowych (np. `["organize", "mail", "kb"]`)
- `role[based_on]` - rola bazowa, opcjonalne. Wartości: `"user"`, `"admin"`, `"owner"`, `"guest"` lub ID innej roli własnej. Rola dziedziczy wszystkie uprawnienia bazowej
- `role[custom_privileges]` - uprawnienia własne jako string oddzielony przecinkami/spacjami (np. `"app.crm, report.export"`). Zalecane nazwy z kropką (np. `app.xxx`, `custom.xxx`) dla czytelności

### Aktualizacja roli

```
PATCH /account/roles/:id.json
```

**Parametry:** `role[name]`, `role[privileges][]`, `role[based_on]`, `role[custom_privileges]`

### Usunięcie roli

```
DELETE /account/roles/:id.json
```

Usunąć można tylko role niestandardowe (nie domyślne).

### Sprawdzanie uprawnień własnych

Uprawnienia własne sprawdza się identycznie jak systemowe - przez `has_privilege?("nazwa")`. System automatycznie rozpoznaje czy to uprawnienie systemowe czy własne:

- Jeśli nazwa istnieje w systemowych uprawnieniach - sprawdzane tylko systemowo
- Jeśli nie istnieje - sprawdzane w `custom_privileges` roli (z uwzględnieniem dziedziczenia)

Przykład:

```ruby
has_privilege?("app.crm")        # sprawdza custom_privileges roli
has_privilege?("crm")            # sprawdza systemowe uprawnienia z role.rb
has_privilege?("report.export")  # sprawdza custom_privileges roli
```