Autenticazione

La REST API di SIP Caller autentica le richieste tramite API Key. Ogni API Key ha un token segreto, che la tua applicazione invia nell'intestazione Authorization di ogni richiesta.

Creare una API Key

Le API Key vengono create dalla Console Web, in Impostazioni > API Keys, da un utente con il ruolo di Amministratore. Durante la creazione della chiave, scegli:

• Un nome, per identificare l'applicazione che la utilizza.
• Una data di scadenza. Dopo tale data, la chiave smette di funzionare. La scadenza non può essere estesa in seguito.
• I ruoli concessi alla chiave, che definiscono cosa può fare l'applicazione. I ruoli non possono essere modificati in seguito.

Quando la chiave viene creata, SIP Caller ne mostra il token una sola volta. Copialo e conservalo in un posto sicuro, ad esempio un gestore di segreti. SIP Caller non memorizza il token, quindi non può essere recuperato: se lo perdi, crea una nuova API Key.

Consulta API Keys per una guida passo passo.

Autenticare le richieste

Invia il token come token Bearer nell'intestazione Authorization:

Authorization: Bearer API_KEY_TOKEN

Ogni richiesta deve essere autenticata. Tieni presente che:

• Una API Key appartiene a un solo account, quindi l'ACCOUNT_ID nell'URL deve essere l'account in cui è stata creata la chiave.
• Le richieste devono essere effettuate tramite HTTPS.
• Il token è un segreto, e concede l'accesso al tuo account. Non includerlo nel codice lato client, come pagine web o app mobili, e non salvarlo nei repository di codice sorgente.

Ruoli

Ogni endpoint richiede che la API Key abbia almeno uno dei seguenti ruoli:

Ruolo	Consente
Amministratore Campagne	Accesso completo a campagne, numeri delle campagne, liste nere, elenchi di contatti e rapporti delle campagne.
Lettore Campagne	Accesso in sola lettura a campagne, numeri delle campagne, liste nere, elenchi di contatti e rapporti delle campagne.
Amministratore Numeri Campagna	Leggere, aggiungere ed eliminare i numeri delle campagne. Può essere limitato a campagne specifiche.
Fornitore Numeri Campagna	Aggiungere numeri alle campagne, senza poterli leggere né eliminare. Può essere limitato a campagne specifiche.

Concedi a ogni applicazione solo i ruoli di cui ha bisogno. Ad esempio, un modulo web che invia nuovi lead a una campagna ha bisogno solo del ruolo Fornitore Numeri Campagna, limitato a quella campagna.

Errori di autenticazione

Stato	Quando
401 Unauthorized	L'intestazione Authorization è assente, oppure il token è malformato, non valido o scaduto.
403 Forbidden	Il token è valido, ma la API Key è stata eliminata, appartiene a un altro account, o non ha un ruolo che consente l'operazione.

Consulta Errori per il formato delle risposte di errore.

Revocare una API Key

Per revocare l'accesso di un'applicazione, elimina la sua API Key da Impostazioni > API Keys. Le richieste effettuate con il token di una chiave eliminata falliscono immediatamente con 403 Forbidden.

Ti consigliamo di ruotare periodicamente le chiavi: crea una nuova chiave, aggiorna la tua applicazione per utilizzarla, e poi elimina quella vecchia.