# Autenticazione

> Chiavi API, ambiti di lettura e scrittura, revoca delle chiavi e loro sicurezza.

L'API utilizza chiavi API segrete. Ogni chiave appartiene a uno spazio di lavoro.

## Invia la chiave

Inserisci la chiave nell'intestazione `Authorization` come token di accesso:

```http
GET /api/v1/workspace HTTP/1.1
Host: tradecatalog.app
Authorization: Bearer tc_live_Xk2…
```

```bash
curl https://tradecatalog.app/api/v1/workspace \
  -H "Authorization: Bearer $TRADECATALOG_API_KEY"
```

Le chiavi iniziano sempre con `tc_live_`. Non esistono chiavi di prova: prova le cose su uno spazio di lavoro con dati di esempio, o leggi prima di scrivere.

## Crea una chiave

Solo il **proprietario** dello spazio di lavoro o un **amministratore** può creare chiavi, in **Impostazioni → API**.

| Impostazione        | Cosa significa                                                                                                              |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Nome                | Il tuo etichettatura, ad esempio “Sincronizzazione stock Sage”. Visualizzato in Impostazioni e nel registro delle attività. |
| Solo lettura        | Richieste `GET` solo.                                                                                                       |
| Lettura e scrittura | Anche `PUT /products`, `PUT /customers` e `PATCH /orders/{id}`.                                                             |

La chiave viene mostrata **una sola volta**. Conserviamo solo un hash SHA-256, quindi nessuno di TradeCatalog può vederla di nuovo. Le Impostazioni mostrano i primi caratteri (come `tc_live_Xk2m…`) per poter distinguere le chiavi.

Uno spazio di lavoro può avere fino a **20 chiavi attive**. Assegna a ogni sistema la propria chiave, in modo da poter revocare una senza danneggiare le altre.

## Chi può avere chiavi

Lo spazio di lavoro ha bisogno di una di queste per creare chiavi:

- una sottoscrizione attiva
- un trial Pro
- un account di prova (organizzato con Happy Webs)

Le aree di lavoro di demo non possono creare o utilizzare chiavi.

Se la sottoscrizione scade, hai 14 giorni di grazia. Dopo questo periodo, l'area di lavoro torna a Free. Le chiavi esistenti possono ancora leggere, ma le scritture API falliscono con `403 read_only` fino a quando Pro non è nuovamente attivo. Le modifiche al catalogo e gli ordini degli acquirenti nell'app continuano a funzionare.

## Cosa può fare una chiave

Una chiave agisce con le **autorizzazioni della persona che l'ha creata**, come sono attualmente. Una chiave creata da un proprietario o un amministratore può leggere ogni cliente, ogni prezzo del cliente, ogni ordine e il registro delle attività. Trattala come la password di quella persona. Una chiave creata da qualcuno limitato ai propri clienti o aree vede solo quei clienti e i loro ordini, prezzi e attività; qualsiasi altro cliente o ordine restituisce `404`, lo stesso di uno che non esiste, e i cambiamenti dei prezzi restituiscono `403`.

Se quella persona riceve successivamente un ruolo più ristretto, la chiave si restringe con loro: una scrittura che il nuovo ruolo non permette fallisce con `403 forbidden`, lo stesso dell'app. Se lasciano l'area di lavoro, la chiave smette di funzionare con `401 key_owner_removed`. Crea una nuova chiave da qualcuno che ha ancora accesso.

## Ultima utilizzazione e revoca

Impostazioni mostra quando ogni chiave è stata utilizzata l'ultima volta (aggiornato al massimo una volta all'ora). Scegli **Revoca** per bloccare immediatamente una chiave. La prossima richiesta con essa otterrà `401 unauthorized`. Le chiavi revocate non possono essere ripristinate.

## Chi sono le modifiche registrate

Le scritture appaiono nel registro delle attività dell'area di lavoro come `API key “Sage stock sync”`. I cambiamenti dello stato degli ordini vengono registrati contro la persona che ha creato la chiave.

## Mantieni le chiavi al sicuro

- Mantieni le chiavi sul tuo server, nelle variabili d'ambiente o in un gestore delle credenziali.
- Non inserire mai una chiave in una pagina web, un'estensione del browser o un'app mobile. L'API non permette richieste del browser (CORS) per questo motivo.
- Non committare mai una chiave in git. Se lo fai, revocala e crea una nuova.
- Usa una chiave di sola lettura ovunque tu abbia bisogno solo di leggere.

## Errori

| Status | Codice               | Perché                                                                                                                                                    |
| ------ | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401    | `unauthorized`       | Nessun header `Authorization`, uno malformato, una chiave sconosciuta o revocata, o un'area di lavoro di demo. La risposta ha `WWW-Authenticate: Bearer`. |
| 401    | `key_owner_removed`  | La persona che ha creato la chiave non ha più accesso all'area di lavoro. Crea una nuova chiave.                                                          |
| 403    | `insufficient_scope` | Una chiave di sola lettura ha provato a scrivere.                                                                                                         |
| 403    | `forbidden`          | La persona che ha creato la chiave non è autorizzata a farlo (ad esempio, un Viewer non può scrivere).                                                    |
| 403    | `read_only`          | Le scritture API non sono disponibili sul piano Free.                                                                                                     |

Vedi [Errori](/docs/api/errors) per l'elenco completo.

**Le app AI utilizzano un accesso diverso:** Claude, ChatGPT e altri client MCP non utilizzano chiavi API. Ogni persona si registra con il proprio account tramite OAuth. Vedi [MCP](/docs/mcp).