# Chiavi API per gli agenti: lettura, scrittura, pubblicazione e un registro di audit che leggerai davvero

_2026-10-01 · Dare agli agenti IA chiavi API Shager in sicurezza: cosa consentono read, write e publish, la rivendicazione, conservazione, limiti, rotazione e audit._

Dai a ogni agente la chiave Shager più limitata che copra il suo compito: `read` per i report, `write` per le bozze e `publish` solo per il passaggio che programma i post. Tieni le chiavi nelle variabili d'ambiente o nella configurazione del client MCP, mai nei prompt. Revocale e ruotale dalla dashboard degli agenti e leggi il suo registro di audit, che elenca ogni chiamata fatta da un agente, almeno una volta a settimana finché un nuovo agente non si è assestato.

Questa è la regola. Il resto dell'articolo spiega il ragionamento e i meccanismi, perché una regola che nessuno capisce viene aggirata alla prima occasione in cui dà fastidio.

## Cosa può fare ciascun permesso?

Ogni chiave Shager ha uno o più dei tre permessi disponibili. Ogni operazione dell'API dichiara il permesso di cui ha bisogno: lo vedi come `x-scope` su ciascuna operazione nel [documento OpenAPI](https://app.shager.ai/api/v1/openapi.json). Gli strumenti MCP sono le stesse operazioni, quindi le stesse regole valgono anche via MCP.

| Permesso | Operazioni |
|---|---|
| read | whoami, list_workspaces, list_channels, list_groups, list_posts, get_post, get_analytics |
| write | create_workspace, create_connect_link, create_group, upload_media_from_url, create_post, request_approval, cancel_post |
| publish | schedule_post |

Due cose di questa tabella meritano attenzione.

Primo, `publish` contiene una sola operazione, ed è quella che manda online i contenuti sugli account dei clienti. Isolarla è proprio lo scopo. Un agente può fare quasi tutto il lavoro, dal caricamento dei media alla scrittura dei testi per account fino all'invio dei link di approvazione, senza mai poter mettere un post su una pagina.

Secondo, `cancel_post` sta sotto `write`. Un agente che scrive bozze può riportare a bozza un post programmato. È voluto: fermare un errore dovrebbe essere più facile che commetterlo.

Una chiave usata senza il permesso necessario riceve un errore nel formato standard, `{ "error": { "code", "message" } }`, con HTTP 403. Gli agenti dovrebbero segnalare quell'errore invece di cercare un modo per aggirarlo, e le tue istruzioni permanenti dovrebbero dirlo chiaramente.

## Da dove arrivano le chiavi

Le strade sono due.

**Una persona crea la chiave** su `app.shager.ai/dashboard/agents`, scegliendo i permessi. È la strada normale per un'agenzia che aggiunge un agente a un account esistente.

**L'agente si registra da solo.** Un agente senza account chiama `POST https://app.shager.ai/api/v1/agent/signup` con un `agent_name` e, idealmente, un `contact_email` della persona di riferimento. Riceve una `api_key`, mostrata una sola volta, e un `claim_url`. La chiave funziona subito in una sandbox, che può creare fino a cinque workspace, caricare media, creare bozze e leggere. Non può programmare né pubblicare, creare link di collegamento per i clienti o inviare richieste di approvazione.

```bash
curl -s https://app.shager.ai/api/v1/agent/signup \
  -H "Content-Type: application/json" \
  -d '{"agent_name":"Northwind content agent (Claude Code)",
       "contact_email":"ops@northwind-agency.example",
       "purpose":"Draft weekly posts for 3 retail clients"}'
```

Queste restrizioni cadono solo quando una persona apre `claim_url`, accede e rivendica l'organizzazione. In quel momento la persona decide se la chiave dell'agente riceve anche `publish`. Se nessuno la rivendica, la sandbox scade dopo sette giorni. La procedura completa è pubblicata in [/auth.md](/auth.md) e la guida passo passo è in [registrazione autonoma e rivendicazione degli agenti](/en/blog/agent-self-signup-and-claim).

La scelta di progetto dietro tutto questo è semplice: un agente può esplorare e preparare da solo, ma collegare account reali e pubblicarci sopra passa sempre da una persona.

## Come dovrebbero conservare e inviare le chiavi gli agenti?

Le chiavi Shager sono bearer token inviati come `Authorization: Bearer shgr_live_...`. La caratteristica che definisce un bearer token, come dice l'[RFC 6750](https://www.rfc-editor.org/rfc/rfc6750), è che chiunque lo possieda può usarlo. Nient'altro prova l'identità. Quindi tutto il lavoro consiste nel non farselo sfuggire.

In pratica:

1. **Variabili d'ambiente, richiamate dalla configurazione.** Claude Code supporta l'espansione `${VAR}` negli header di `.mcp.json`, come indicato nella sua [documentazione MCP](https://code.claude.com/docs/en/mcp). Il file si può mettere nel repository; la chiave resta nell'ambiente.
2. **Mai in un prompt.** Una chiave incollata in chat finisce nelle trascrizioni e nei log, e a volte nelle conversazioni condivise.
3. **Mai nella cartella di un cliente.** Se tieni cartelle di contesto per ogni cliente, le chiavi non vanno lì. Quelle cartelle vengono condivise e compresse in zip.
4. **Una chiave per ogni ruolo di agente.** Un job di report, un agente che scrive bozze e un passaggio di programmazione non dovrebbero condividere una chiave. Quando una trapela, ne revochi una sola.

```json
{
  "mcpServers": {
    "shager": {
      "type": "http",
      "url": "https://app.shager.ai/api/mcp",
      "headers": { "Authorization": "Bearer ${SHAGER_DRAFT_KEY}" }
    }
  }
}
```

Il server MCP di Shager accetta questo header della chiave API. I client che si collegano invece con l'accesso OAuth, come un connettore personalizzato in Claude o ChatGPT, hanno lo stesso tipo di controllo: una persona approva il collegamento nella schermata di consenso di Shager, la pubblicazione è una casella separata e disattivata per impostazione predefinita, e il collegamento compare nello stesso registro di audit. [Shager e ChatGPT](/it/blog/shager-and-chatgpt) spiega passo per passo la configurazione in ChatGPT.

## Rotazione senza interruzioni

Le chiavi vanno ruotate quando se ne va una persona che vi aveva accesso, quando una chiave potrebbe essere stata esposta e secondo un calendario che riesci a rispettare. La sequenza che evita buchi:

1. Crea nella dashboard una nuova chiave con gli stessi permessi.
2. Aggiorna la variabile d'ambiente dove gira l'agente.
3. Esegui `whoami` con la nuova chiave per verificare che funzioni e mostri i permessi previsti.
4. Revoca la vecchia chiave.

La revoca ha effetto su ogni chiamata fatta con quella chiave, sia MCP sia REST.

## Anche i limiti di richieste fanno parte della sicurezza

Ogni chiave è limitata a 120 richieste al minuto. Un agente che si comporta bene non ci si avvicina mai: un'intera bozza settimanale per un cliente richiede qualche decina di chiamate. Quando un agente riceve un HTTP 429, di solito significa che è finito in un loop, cioè ritenta la stessa chiamata fallita all'infinito. Le tue istruzioni dovrebbero trattare il 429 come un segnale di stop, non come un motivo per ritentare più in fretta. Rallenta, segnala e lascia che controlli una persona.

## Leggere il registro di audit

La dashboard degli agenti mostra un registro di audit di ogni chiamata degli agenti. Serve solo se qualcuno lo legge. Cosa cercare nelle prime settimane con un nuovo agente:

1. **Chiamate che non ti aspettavi.** Un agente di report che chiama `create_post` vuol dire che le sue istruzioni o la sua chiave sono sbagliate.
2. **Sconfinamenti tra workspace.** Chiamate che toccano un cliente che non c'entrava con il compito. È il primo segnale dell'errore tra clienti di cui parliamo in [un agente, molti clienti](/en/blog/one-agent-many-clients).
3. **Raffiche di errori.** Una serie di 403 vuol dire che l'agente continua a tentare qualcosa fuori dal suo permesso. Correggi le istruzioni, non il permesso.

Dopo qualche settimana senza problemi, basta una rapida occhiata settimanale.

## Domande frequenti

### L'agente dovrebbe mai avere il permesso publish?

Può averlo, una volta che ti fidi delle sue bozze e hai un passaggio di revisione: link di approvazione per il cliente o un revisore interno. Uno schema che funziona bene è tenere `publish` su una chiave separata, usata solo da un breve passaggio di programmazione scritto come script, così l'agente che scrive non è lo stesso che pubblica.

### Cosa succede alla chiave dell'agente quando la sandbox viene rivendicata?

L'organizzazione passa alla persona e la chiave continua a funzionare al suo interno. Al momento della rivendicazione la persona sceglie se quella chiave può anche programmare e pubblicare. Può revocarla o crearne di nuove dalla dashboard in qualsiasi momento.

### Si può limitare una chiave a un solo workspace cliente?

I permessi limitano cosa può fare una chiave, non su quale workspace agisce. Separa i clienti con i workspace, un contesto per ogni cliente e l'abitudine di individuare il workspace per nome prima di ogni scrittura, e usa chiavi separate per ogni ruolo, così una revoca resta chirurgica.

## Da dove continuare

Se stai configurando il tuo primo agente, il [punto di ingresso per gli agenti](/en/agents) mostra entrambe le strade per ottenere una chiave. Parti con una chiave `write` e aggiungi `publish` solo quando le bozze se lo sono meritato.

---
Source: https://shager.ai/it/blog/api-keys-scopes-and-audit