# API: membri del team, ruoli e token di accesso

_API · 6 min di lettura · Aggiornato 2026-10-22 · https://lanachat.ai/guides/it/api-team/_

Il tuo **team** è composto dalle persone che lavorano nello spazio di lavoro. Ogni **membro** ha un **ruolo** (predefinito o personalizzato) che determina cosa può fare, su quali creator lavora e una chiave di accesso personale per effettuare il login. I **token di accesso** sono le chiavi per l'API e per la connessione MCP. Tutti questi endpoint richiedono un token **owner**: negli esempi, `$LANACHAT_TOKEN` ne contiene uno.

## Endpoint

| Method | Path | Descrizione | Permesso | Stato |
|---|---|---|---|---|
| GET | `/members` | Elenca i membri (`status=active,disabled`, `role_id=`, `q=`) | `owner` | Planned |
| POST | `/members` | Aggiunge un membro con ruolo e creator | `owner` | Planned |
| GET | `/members/{id}` | Un membro, ultima attività e override | `owner` | Planned |
| PATCH | `/members/{id}` | Cambia ruolo, creator, override; disabilita o abilita | `owner` | Planned |
| DELETE | `/members/{id}` | Elimina un membro (i suoi messaggi passati mantengono il nome) | `owner` | Planned |
| POST | `/members/{id}/access-key` | Crea una chiave di accesso personale (mostrata una volta) | `owner` | Planned |
| POST | `/members/{id}/invitation` | Invia via e-mail una chiave di accesso al membro | `owner` | Planned |
| DELETE | `/members/{id}/access-key` | Revoca la chiave del membro: viene disconnesso | `owner` | Planned |
| GET | `/roles` | Ruoli predefiniti e personalizzati con tabella permessi | `owner` | Planned |
| POST | `/roles` | Crea un ruolo personalizzato | `owner` | Planned |
| PATCH | `/roles/{id}` | Rinomina un ruolo o cambia i permessi | `owner` | Planned |
| DELETE | `/roles/{id}` | Elimina un ruolo personalizzato non assegnato | `owner` | Planned |
| GET | `/tokens` | Token di accesso API e MCP (`include_revoked=true`) | `owner` | Planned |
| POST | `/tokens` | Crea un token con permessi (mostrato una volta) | `owner` | Planned |
| PATCH | `/tokens/{id}` | Rinomina un token o cambia i permessi | `owner` | Planned |
| POST | `/tokens/{id}/rotate` | Sostituisce il segreto; il vecchio si disattiva subito | `owner` | Planned |
| DELETE | `/tokens/{id}` | Revoca un token | `owner` | Planned |

## L'oggetto membro

```json
{
  "id": "mem_4",
  "name": "Ana",
  "email": "ana@mia-agency.com",
  "status": "active",
  "role_id": "role_chatter",
  "creator_ids": ["cr_lea", "cr_mia"],
  "overrides": { "billing.read": false, "fans.export": true },
  "access_key": { "active": true, "created_at": "2026-09-20T09:00:00Z" },
  "last_active_at": "2026-10-06T13:40:00Z"
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Inizia con `mem_` |
| `name` | string | Il suo nome nella Console |
| `email` | string o null | Dove arriva l'invito |
| `status` | string | `active` o `disabled` |
| `role_id` | string | Il suo ruolo |
| `creator_ids` | array di stringhe | I creator su cui lavora |
| `overrides` | object | Permessi impostati solo per questo membro, oltre al ruolo |
| `access_key` | object | Se ha una chiave di accesso personale `active` e da quando; mai la chiave stessa |
| `last_active_at` | string o null | La sua ultima attività |

Un membro disabilitato non può effettuare il login e mantiene la sua storia, ruolo e creator.

## L'oggetto ruolo

```json
{
  "id": "role_chatter",
  "name": "Chatter",
  "builtin": true,
  "permissions": { "live.read": true, "live.reply": true, "fans.read": true, "fans.export": false, "billing.read": false },
  "members": 6
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Il ruolo |
| `name` | string | Il suo nome |
| `builtin` | boolean | `true` per Owner, Manager e Chatter |
| `permissions` | object | Una chiave per ogni riga della tabella permessi, `true` o `false` |
| `members` | integer | Quanti membri lo hanno |

Le chiavi dei permessi seguono le righe della tabella permessi in **Team Management › Roles**, raggruppate per area: Dashboard, Creators, AI Brain, Conversations, Vault, Scripts, Playground, Telegram e Employees. **Owner** ha sempre tutti i permessi e non può essere modificato. **Manager** e **Chatter** sono predefiniti: puoi cambiare i loro permessi ma non rinominarli o eliminarli.

## L'oggetto token di accesso

```json
{
  "id": "tok_31",
  "name": "Reporting script",
  "permissions": ["can_fan_read", "can_sales_read"],
  "status": "active",
  "created_at": "2026-10-06T15:10:00Z",
  "expires_at": "2027-01-04T15:10:00Z"
}
```

| Campo | Tipo | Descrizione |
|---|---|---|
| `id` | string | Inizia con `tok_` |
| `name` | string | Fino a 100 caratteri, obbligatorio |
| `permissions` | array di stringhe | I [permessi](https://lanachat.ai/guides/it/api-overview/) che ha |
| `status` | string | Attivo, scaduto o revocato |
| `created_at`, `expires_at` | string | ISO 8601, UTC |
| `token` | string | Il segreto, solo nella risposta che lo crea o ruota |

## Membri

### Elenca membri

`GET /members` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `status` | string | No | `active` o `disabled`; entrambi separati da virgola |
| `role_id` | string | No | Solo membri con questo ruolo |
| `q` | string | No | Parte di un nome |
| `limit`, `cursor` | number, string | No | [Paginazione](https://lanachat.ai/guides/it/api-overview/) |

```bash
curl "https://api.lanachat.ai/v1/members?status=active&role_id=role_chatter" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

```json
{
  "data": [
    { "id": "mem_4", "name": "Ana", "email": "ana@mia-agency.com", "status": "active", "role_id": "role_chatter", "creator_ids": ["cr_lea", "cr_mia"], "overrides": {}, "access_key": { "active": true, "created_at": "2026-09-20T09:00:00Z" }, "last_active_at": "2026-10-06T13:40:00Z" }
  ],
  "next_cursor": null
}
```

### Aggiungi un membro

`POST /members` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | Sì | Il suo nome |
| `email` | string | No | Necessario per inviare un invito |
| `role_id` | string | Sì | Un ruolo predefinito o personalizzato |
| `creator_ids` | array di stringhe | No | I creator su cui lavora |

```bash
curl -X POST https://api.lanachat.ai/v1/members \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Ana", "email": "ana@mia-agency.com", "role_id": "role_chatter", "creator_ids": ["cr_lea"]}'
```

La risposta è il nuovo membro (`201`), attivo, senza ancora una chiave di accesso.

### Ottieni un membro

`GET /members/{id}` · `owner`

```bash
curl https://api.lanachat.ai/v1/members/mem_4 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La risposta è l'oggetto membro. Un id sconosciuto risponde con `404`.

### Aggiorna un membro

`PATCH /members/{id}` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `role_id` | string | No | Nuovo ruolo |
| `creator_ids` | array di stringhe | No | Sostituisce la lista dei creator |
| `overrides` | object | No | Permessi solo per questo membro |
| `status` | string | No | `active` o `disabled` |

```bash
curl -X PATCH https://api.lanachat.ai/v1/members/mem_4 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"creator_ids": ["cr_lea", "cr_mia"], "overrides": {"fans.export": true}}'
```

La risposta è il membro aggiornato. `status: "disabled"` blocca l'accesso immediatamente; ruolo e creator sono mantenuti.

### Elimina un membro

`DELETE /members/{id}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/members/mem_4 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Il membro viene rimosso e i suoi creator vengono dissociati. I suoi messaggi passati mantengono il nome. Per conservarli per dopo, disabilitalo invece.

## Chiavi di accesso personali

I membri del team non usano una password: accedono con una chiave di accesso personale. Le chiavi iniziano con `emp_`.

### Crea una chiave di accesso

`POST /members/{id}/access-key` · `owner`

```bash
curl -X POST https://api.lanachat.ai/v1/members/mem_4/access-key \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

```json
{ "member_id": "mem_4", "sign_in_url": "https://app.lanachat.ai/login/?mode=employee", "access_key": "emp_6Yq2…", "shown_once": true }
```

Invia sia l'indirizzo di accesso sia la chiave alla persona tramite un canale di fiducia. Un membro disabilitato risponde `409`: abilitalo prima.

### Invia via e-mail una chiave di accesso

`POST /members/{id}/invitation` · `owner`

```bash
curl -X POST https://api.lanachat.ai/v1/members/mem_4/invitation \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

La chiave viene inviata all'indirizzo e-mail sulla sua scheda. Un membro senza e-mail, o disabilitato, risponde `409`.

### Revoca una chiave di accesso

`DELETE /members/{id}/access-key` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/members/mem_4/access-key \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

La chiave si disattiva immediatamente e il membro viene disconnesso. Crea una nuova chiave per farlo rientrare.

## Ruoli

### Elenca ruoli

`GET /roles` · `owner`

```bash
curl https://api.lanachat.ai/v1/roles \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Una lista di oggetti ruolo: Owner, Manager, Chatter e i tuoi ruoli personalizzati.

### Crea un ruolo personalizzato

`POST /roles` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | Sì | Il nome del ruolo |
| `permissions` | object | No | Le righe da attivare; le altre sono disattivate |

```bash
curl -X POST https://api.lanachat.ai/v1/roles \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Night chatter", "permissions": {"live.read": true, "live.reply": true, "fans.read": true}}'
```

La risposta è il nuovo ruolo (`201`) con `builtin: false`.

### Aggiorna un ruolo

`PATCH /roles/{id}` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | No | Nuovo nome (solo ruoli personalizzati) |
| `permissions` | object | No | Le righe da modificare; le altre restano |

```bash
curl -X PATCH https://api.lanachat.ai/v1/roles/role_chatter \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions": {"fans.export": false}}'
```

La modifica si applica subito a tutti i membri con quel ruolo, tranne i loro override personali. Modificare Owner, o rinominare Manager o Chatter, risponde `409`.

### Elimina un ruolo personalizzato

`DELETE /roles/{id}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/roles/role_night \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Eliminare un ruolo ancora assegnato a membri risponde `409`: assegna loro prima un altro ruolo. I ruoli predefiniti non possono essere eliminati.

## Token di accesso

### Elenca token

`GET /tokens` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `include_revoked` | boolean | No | `true` per includere anche i token revocati |

```bash
curl "https://api.lanachat.ai/v1/tokens?include_revoked=true" \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Una lista di oggetti token di accesso, senza il loro segreto.

### Crea un token

`POST /tokens` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | Sì | A cosa serve, fino a 100 caratteri |
| `permissions` | array di stringhe | Sì | I [permessi](https://lanachat.ai/guides/it/api-overview/) che ottiene |
| `expires_in_days` | integer | No | Quando scade |

```bash
curl -X POST https://api.lanachat.ai/v1/tokens \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"name": "Reporting script", "permissions": ["can_fan_read", "can_sales_read"], "expires_in_days": 90}'
```

```json
{ "id": "tok_31", "name": "Reporting script", "token": "lc_live_8f2c1d0e9b7a4c6f", "permissions": ["can_fan_read", "can_sales_read"], "expires_at": "2027-01-04T15:10:00Z" }
```

`token` è presente solo in questa risposta. Un token non può mai avere più permessi del token owner che lo ha creato. Un nome mancante risponde `400`.

### Aggiorna un token

`PATCH /tokens/{id}` · `owner`

| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
| `name` | string | No | Nuovo nome |
| `permissions` | array di stringhe | No | Sostituisce i permessi |

```bash
curl -X PATCH https://api.lanachat.ai/v1/tokens/tok_31 \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"permissions": ["can_sales_read"]}'
```

La risposta è il token, senza il segreto. Disattivare `can_engine` rimuove anche i permessi di publishing, Advanced AI e report esperimenti. Un token revocato risponde `409`.

### Ruota un token

`POST /tokens/{id}/rotate` · `owner`

```bash
curl -X POST https://api.lanachat.ai/v1/tokens/tok_31/rotate \
  -H "Authorization: Bearer $LANACHAT_TOKEN" \
  -H "Idempotency-Key: $(uuidgen)"
```

La risposta è il token con un nuovo segreto `token`, mostrato una volta. Il vecchio segreto si disattiva subito, quindi aggiorna subito il tuo script. Un token revocato risponde `409`.

### Revoca un token

`DELETE /tokens/{id}` · `owner`

```bash
curl -X DELETE https://api.lanachat.ai/v1/tokens/tok_31 \
  -H "Authorization: Bearer $LANACHAT_TOKEN"
```

Il token si disattiva immediatamente. Un token già revocato risponde `409`.

> Warning: Un token funziona come una password. Revocalo appena smetti di usarlo o pensi sia stato compromesso.

## Articoli correlati

- [API LanaChat: avvio rapido, autenticazione ed errori](https://lanachat.ai/guides/it/api-overview/)
- [Gestione del team: dipendenti e ruoli](https://lanachat.ai/guides/it/team-and-roles/)
- [Ruoli personalizzati e la tabella dei permessi](https://lanachat.ai/guides/it/custom-roles/)
- [Chiavi di accesso personali](https://lanachat.ai/guides/it/personal-access-keys/)