Passa al contenuto principale

Autenticazione

Ogni richiesta porta una chiave API nell'intestazione X-API-Key.

curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://vostro-server/api/v1/integration/connection

Ottenere una chiave​

Le chiavi si generano dentro Mover.Glass, nell'anagrafica dell'integratore. Chiedetele a chi amministra la vostra installazione.

Due cose da sapere prima di chiederla:

La chiave appare una volta sola. Ne conserviamo solo l'hash, quindi non possiamo recuperarla in seguito — se si perde, l'unica strada è revocarla e generarne un'altra. Copiatela subito dove dovrà vivere.

Usate una chiave per installazione. Non una per azienda. Se una macchina viene compromessa o dismessa, quella chiave viene revocata senza disturbare nessun altro. Ogni chiave ha un nome, così l'elenco resta leggibile anche fra un anno.

GET /api/v1/integration/connection​

Verificare che funzioni.

Prima di ogni altra cosa, confermate l'URL e la chiave:

curl -H "X-API-Key: mgi_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
     https://vostro-server/api/v1/integration/connection
{
  "connected": true,
  "authenticatedByApiKey": true,
  "apiKeyId": 12,
  "email": "integratore@cliente.com",
  "serverUtc": "2026-09-18T14:02:11Z"
}

Vale la pena collegare questa chiamata al vostro monitoraggio. Risponde a tre domande in una volta: il server è raggiungibile, la chiave è valida e gli orologi coincidono. La maggior parte dei problemi di integrazione che sembrano misteriosi è una di queste tre.

apiKeyId dice quale chiave ha autenticato. Quando più installazioni condividono un server, è quel numero a distinguerle in una conversazione di assistenza.

Quando una chiave smette di funzionare​

Una chiave revocata o non valida restituisce 401, con un corpo che non vale la pena interpretare.

Trattate 401 come non ripetere. Rimandare la stessa richiesta non cambierà la risposta: la chiave va sostituita. Ripetere una chiave non valida in ciclo è il modo in cui un'integrazione finisce bloccata.

Custodire la chiave​

La chiave è una credenziale. Stessa cura di una password:

  • Mai nel controllo di versione, mai in una URL, mai in una riga di log
  • In una variabile d'ambiente, in un gestore di segreti o in un file di configurazione cifrato
  • Da ruotare se chi vi aveva accesso lascia l'azienda

Se una chiave trapela, chiedetene la revoca. La revoca è immediata, e generare la sostituta richiede pochi secondi.