# Autenticazione

URL: https://wa.genuka.com/it/docs/authentication
Language: Italian

> Chiavi API, ambito e buone pratiche di rotazione.

Ogni richiesta si autentica con una chiave API nell'header `Authorization`:

```http
Authorization: Bearer pk_live_...
```

> [!WARNING]
> Non maneggi **mai** un token di Meta. Genuka WA custodisce le credenziali della Cloud API e le
> ruota al posto tuo: basta una sola chiave API di Genuka, e dà accesso solo ai tuoi dati.

## Due ambiti di chiave

| Ambito      | Accesso                     | Caso d'uso                                          |
| ----------- | --------------------------- | --------------------------------------------------- |
| **Partner** | Tutti i clienti del partner | Una piattaforma che gestisce numeri per più aziende |
| **Cliente** | Una sola azienda            | Un'azienda che integra solo i propri numeri         |

Una chiave cliente che tenta di accedere a un'altra azienda riceve `403 out_of_scope`. Alcuni
endpoint (fatturazione, utilizzo del piano) richiedono una chiave partner e altrimenti rispondono
`403 partner_key_required`.

## Creare e revocare una chiave

Le chiavi si gestiscono dal portale, in **Sviluppatori**. Una chiave viene mostrata **una sola
volta** alla creazione: Genuka ne conserva solo un'impronta e non può mostrartela di nuovo.

Per ruotare senza interruzioni del servizio: crea la nuova chiave, distribuiscila, verifica il
traffico nei log, poi revoca quella vecchia.

## Risposte di errore

| Stato | Codice                 | Significato                             |
| ----- | ---------------------- | --------------------------------------- |
| `401` | `missing_bearer_token` | Manca l'header `Authorization`          |
| `401` | `invalid_token`        | Chiave sconosciuta o revocata           |
| `403` | `out_of_scope`         | La chiave è limitata a un'altra azienda |
| `403` | `partner_key_required` | Endpoint riservato alle chiavi partner  |

## Sicurezza

* Una chiave API è un segreto lato server. Non includerla mai in un frontend o in un'app mobile:
  chiunque potrebbe inviare messaggi a tuo nome, a tue spese.
* Usa chiavi distinte per ambiente e per integrazione: così la revoca diventa un'operazione
  chirurgica anziché globale.
* Ogni richiesta viene registrata ed è visibile nel portale.
