# Autenticazione (https://docs.getbeel.com/it/api/authentication)

Chiavi API di test e live, scope e buone pratiche.

Ogni richiesta porta una chiave API nell'header `Authorization`:

![La pagina Chiavi API e MCP: chiavi di test e live, permessi e indirizzo del server MCP.](/screenshots/api-keys-mcp.it.webp)

```bash
curl https://www.getbeel.com/api/v1/me \
  -H "Authorization: Bearer gb_test_..."
```

## Chiavi di test e live [#chiavi-di-test-e-live]

| Prefisso   | Modalità | Cosa succede all'invio                                                      |
| ---------- | -------- | --------------------------------------------------------------------------- |
| `gb_test_` | Test     | L'invio va alla [sandbox](/it/api/sandbox): nessuna fattura arriva allo SDI |
| `gb_live_` | Live     | La fattura viene trasmessa allo SDI e ha valore fiscale                     |

Gli endpoint sono gli stessi. Sviluppa e collauda con una chiave di test e passa a una chiave live solo in produzione. Le letture (`GET`) restituiscono i dati del tuo account in entrambe le modalità.

## Creare e gestire le chiavi [#creare-e-gestire-le-chiavi]

Le chiavi si creano in **Impostazioni → Chiavi API e MCP** nell'app.

- La chiave viene mostrata **una sola volta**. Getbeel conserva solo un hash e il prefisso (es. `gb_live_a1B2`), che vedi nell'elenco.
- Puoi impostare una scadenza e revocare una chiave in qualsiasi momento.
- Una chiave appartiene a un team e agisce come il membro che l'ha creata: vede solo i dati di quel team.
- Se il membro esce dal team, le sue chiavi vengono revocate. Se perde il permesso di gestire le impostazioni (per esempio diventa revisore), le sue chiavi restano sospese.

## Scope [#scope]

Quando crei una chiave scegli cosa può fare. Una richiesta a un endpoint fuori dagli scope della chiave riceve `403 insufficient_scope`.

| Scope                     | Consente                                                                                                                    |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `account:read`            | `GET /me`, strumento MCP `whoami`                                                                                           |
| `invoices:read`           | `GET /invoices`, `GET /invoices/{id}`, strumenti `list_invoices`, `get_invoice`                                             |
| `received_invoices:read`  | `GET /received-invoices`, strumento `list_received_invoices`                                                                |
| `invoices:validate`       | `POST /invoices/validate`, strumento `validate_invoice`                                                                     |
| `invoices:write`          | `POST /invoices`, `POST /invoices/{id}/send`, strumenti `create_invoice_draft`, `send_invoice`                              |
| `received_invoices:write` | `POST /received-invoices/{id}/approve` e `/reject`, strumento `approve_collected_document` (chiavi live)                    |
| `bank:read`               | Estratti conto, movimenti, riconciliazioni, abbinamenti, elenchi dei non abbinati                                           |
| `bank:write`              | Caricare estratti conto, avviare riconciliazioni, approvare, rifiutare e collegare abbinamenti (chiavi live)                |
| `connections:read`        | `GET /connections`, `GET /forwarding-address`, strumento `list_connections`                                                 |
| `connections:write`       | Collegare caselle email e Stripe, scansionare caselle, sincronizzare Stripe (chiavi live)                                   |
| `taxes:read`              | Scadenzario fiscale (anche `.ics`), adempimenti preparati, posizione IVA stimata                                            |
| `taxes:write`             | Preparare un adempimento (F24) e caricare la quietanza (chiavi live)                                                 |
| `advisors:read`           | `GET /advisors`, strumento `list_advisors`                                                                                  |
| `advisors:write`          | Invitare o rimuovere un commercialista con accesso in sola lettura: `POST /advisors`, `DELETE /advisors/{id}` (chiavi live) |
| `drive:read` | Cartelle, file e link di download: `GET /drive`, `GET /drive/files/{id}/download`, strumenti `list_drive`, `get_drive_file`. I file delle fatture richiedono anche `received_invoices:read`, gli estratti conto `bank:read` |
| `drive:write` | Creare una cartella: `POST /drive/folders`, strumento `create_drive_folder` (chiavi live) |
| `billing:write` | Creare un link "Aggiungi credito" da far pagare a una persona (`POST /billing/topups`, strumento `create_billing_topup`) e un link "Cambia carta" (`POST /billing/payment-method`, strumento `create_billing_card_link`) (chiavi live; mai selezionato di default) |

Gli endpoint che creano e inviano fatture richiedono lo scope `invoices:write`. Le nuove chiavi hanno tutti gli scope selezionati tranne `advisors:write`, che dà a una persona un accesso duraturo ai dati dell'azienda: togli quelli che a un'integrazione non servono. Gli scope non si possono modificare dopo: crea una nuova chiave.

Dai a ogni integrazione solo gli scope che le servono: una chiave che legge soltanto non può inviare fatture.

## Errori di autenticazione [#errori-di-autenticazione]

Tutti con stato `401` e `type: "authentication_error"`:

| `code`              | Significato                                   |
| ------------------- | --------------------------------------------- |
| `missing_api_key`   | Manca l'header `Authorization: Bearer …`      |
| `invalid_api_key`   | La chiave non esiste o è scritta male         |
| `api_key_revoked`   | La chiave è stata revocata                    |
| `api_key_expired`   | La chiave è scaduta                           |
| `api_key_suspended` | Chi l'ha creata non può più gestire le chiavi |

## Buone pratiche [#buone-pratiche]

- Tieni la chiave sul server, in una variabile d'ambiente come `GETBEEL_API_KEY`. Mai nel codice, nel browser o in un'app mobile.
- Usa una chiave per integrazione, così puoi revocarne una senza fermare le altre.
- Se una chiave finisce in un repository o in un log, revocala e creane una nuova.

<Callout title="Client MCP: nessuna chiave">
  Claude, ChatGPT e Cursor si collegano al [server MCP](/it/api/mcp) con
  l'accesso (OAuth 2.1). Il collegamento ha un team, una modalità e degli scope
  come una chiave, e compare in Impostazioni → Chiavi API e MCP → App collegate.
</Callout>
