Ruoli e Permessi

Gestisci i ruoli personalizzati e consulta il catalogo dei permessi che alimenta il controllo degli accessi basato sui ruoli (RBAC) di Replicer.

Endpoint della dashboard

Questi endpoint sono serviti dalla dashboard di Replicer sotto /api/roles e sono autenticati con la sessione della dashboard (il cookie auth_token), non con una chiave API /v1. L'accesso è regolato dai permessi RBAC anziché dagli scope delle chiavi API. I proprietari dell'organizzazione dispongono implicitamente di tutti i permessi.

Ogni endpoint di modifica richiede il permesso roles.manage. L'elenco dei ruoli è disponibile anche a chi possiede team.manage (così i team manager possono assegnare i ruoli).

---

Elenca i ruoli

GET /api/roles

Recupera tutti i ruoli dell'organizzazione corrente, con i ruoli di sistema per primi.

Permesso richiesto: roles.manage oppure team.manage

Risposta 200 OK

{
  "success": true,
  "roles": [
    {
      "id": "clx-role-001",
      "name": "Administrator",
      "description": "Full access to all organization features",
      "permissions": ["agents.manage", "team.manage", "roles.manage"],
      "isSystem": true,
      "memberCount": 3,
      "invitationCount": 0,
      "createdAt": "2026-03-01T10:00:00Z",
      "updatedAt": "2026-03-01T10:00:00Z"
    }
  ]
}

memberCount è il numero di utenti distinti assegnati al ruolo (un utente è contato una sola volta anche se il ruolo è sia il suo ruolo nell'organizzazione sia il suo ruolo attivo). invitationCount è il numero di inviti in sospeso per il ruolo.

---

Elenca i permessi disponibili

GET /api/roles/permissions

Restituisce il catalogo completo dei permessi e i gruppi usati per l'editor dei ruoli. Leggibile da qualsiasi utente autenticato.

Permesso richiesto: nessuno (solo autenticazione)

Risposta 200 OK

{
  "success": true,
  "permissions": [
    "agents.manage",
    "calls.create",
    "campaigns.create",
    "campaigns.start",
    "team.manage",
    "roles.manage"
  ],
  "groups": [
    { "id": "ai", "permissions": ["agents.manage", "knowledge.manage", "tts.manage"] },
    { "id": "organization", "permissions": ["billing.manage", "team.manage", "roles.manage"] }
  ]
}

---

Crea un ruolo

POST /api/roles

Crea un ruolo personalizzato per l'organizzazione.

Permesso richiesto: roles.manage

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	Sì	Nome univoco del ruolo (1–64 caratteri)
description	string	No	Descrizione opzionale (max 256 caratteri)
permissions	string[]	Sì	Almeno una chiave di permesso dal catalogo

Esempio

curl -X POST https://replicer.ai/api/roles \
  -H "Content-Type: application/json" \
  --cookie "auth_token=your_session_token" \
  -d '{
    "name": "Support Agent",
    "description": "Can manage agents and create calls",
    "permissions": ["agents.manage", "calls.create"]
  }'

Risposta 200 OK

{
  "success": true,
  "role": {
    "id": "clx-role-010",
    "name": "Support Agent",
    "description": "Can manage agents and create calls",
    "permissions": ["agents.manage", "calls.create"],
    "isSystem": false,
    "organizationId": "clx-org-001",
    "createdAt": "2026-04-05T10:00:00Z",
    "updatedAt": "2026-04-05T10:00:00Z"
  }
}

Errori

Stato	Quando
400	Chiave di permesso non valida, o esiste già un ruolo con lo stesso nome
403	Manca il permesso roles.manage

---

Aggiorna un ruolo

PATCH /api/roles/:id

Aggiorna nome, descrizione o permessi di un ruolo. Tutti i campi sono opzionali; vengono modificati solo i campi forniti.

Permesso richiesto: roles.manage

Corpo della richiesta

Campo	Tipo	Obbligatorio	Descrizione
name	string	No	Nuovo nome univoco (1–64 caratteri)
description	string | null	No	Nuova descrizione (max 256 caratteri)
permissions	string[]	No	Elenco di permessi sostitutivo (min 1 voce)

Risposta 200 OK

{
  "success": true,
  "role": {
    "id": "clx-role-010",
    "name": "Support Agent",
    "description": "Updated description",
    "permissions": ["agents.manage", "calls.create", "campaigns.create"],
    "isSystem": false,
    "organizationId": "clx-org-001",
    "createdAt": "2026-04-05T10:00:00Z",
    "updatedAt": "2026-04-06T09:00:00Z"
  }
}

Errori

Stato	Quando
400	Chiave di permesso non valida, nome duplicato, o rimozione di roles.manage dall'ultimo ruolo che lo possiede
403	Manca il permesso roles.manage
404	Ruolo non trovato in questa organizzazione

---

Elimina un ruolo

DELETE /api/roles/:id

Elimina un ruolo personalizzato.

Permesso richiesto: roles.manage

Risposta 200 OK

{
  "success": true
}

Errori

Stato	Quando
400	I ruoli di sistema non possono essere eliminati, il ruolo è ancora assegnato a membri o inviti, oppure è l'ultimo ruolo con roles.manage
403	Manca il permesso roles.manage
404	Ruolo non trovato in questa organizzazione