Sicurezza e autorizzazioni
==========================

Le applicazioni che hanno la necessità di utilizzare le API
**devono essere preventivamente concordate con GestionaleAuto.com**. Se la vostra applicazione è stata approvata,
otterrete un **token** [#token]_ con cui poter interagire con le API.
Il token potrà essere utilizzato solo da indirizzi IP preventivamente comunicati e autorizzati.

.. _token_def:

Il token viene inviato alle API attraverso un apposito *header* da inserire **in ogni chiamata HTTP**:

.. code-block:: javascript

    Authorization: Token <token>

dove ``token`` viene sostituito dal *token* ottenuto da GestionaleAuto.com.

Se il *token* è valido, la richiesta effettuata sarà inviata all'*entry point* invocato, altrimenti si otterrà un codice
di errore **401**, **403** o **500** a seconda del :ref:`problema rilevato <codici_risposta_http>`.

Errori di autorizzazione
++++++++++++++++++++++++

In caso di errore di autorizzazione (codice di errore **401**, **403** o **500**) la risposta in formato *JSON*
è la seguente:

.. code-block:: javascript

  {
    "error": "error message"
  }


Il campo ``error`` conterrà un messaggio di errore che indica il motivo per cui l'autenticazione è fallita:

+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Codice errore HTTP | Messaggio di errore                                                                                                                                                  | Significato                                                                                                                                                                                                                                                                                               |
+====================+======================================================================================================================================================================+===========================================================================================================================================================================================================================================================================================================+
| 401                | Missing Authorization Header                                                                                                                                         | Non è stato fornito, tramite *header*, il *token* di autenticazione                                                                                                                                                                                                                                       |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401                | The authorization token provided does not exists                                                                                                                     | Il token fornito non è mai stato generato nel sistema                                                                                                                                                                                                                                                     |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 401                | Malformed Authorization Header. Please check documentation on how to provide authorization token                                                                     | L'header contenente il token non è nel formato corretto o non è stato fornito un token valido di 64 caratteri                                                                                                                                                                                             |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403                | The authorization token provided is expired                                                                                                                          | Il token in vostro possesso è scaduto. `contattate GestionaleAuto.com <mailto:developers@gestionaleauto.com?subject=[API]%20Token%20scaduto>`_ per risolvere il problema                                                                                                                                  |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403                | Please set the user identification you want to use according to API documentation. Authorization token provided has more than one user identification associated     | Il *token* permette l'accesso a più utenti e :ref:`non è stato specificato quale utilizzare <http_request>` (si sta utilizzando l'entry point con il prefisso *me* quando non si dovrebbe)                                                                                                                |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403                | Authorization token provided does not allow operations on this user identification                                                                                   | Si sta cercando di operare su un cliente di GestionaleAuto.com su cui non si è autorizzati. Se dovreste essere in grado di effettuare operazioni sull'utente, `contattateci e risolveremo il problema <mailto:developers@gestionaleauto.com?subject=[API]%20Utente%20non%20configurato%20nel%20token>`__  |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403                | Authorization token provided can not access this entry point                                                                                                         | È stato richiesto l'accesso ad un *entry point* su cui non si è autorizzati                                                                                                                                                                                                                               |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 403                | Authorization token provided does not allow operations from this IP                                                                                                  | L'IP di provenienza del client delle API non è stato autorizzato da GestionaleAuto.com. Se questo non è corretto `contattateci e risolveremo il problema <mailto:developers@gestionaleauto.com?subject=[API]%IP%20non%20configurato%20nel%20token>`__                                                     |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 500                | API Authorization not properly configured. Please contact GestionaleAuto.com reporting this error                                                                    | Vi è un errore di configurazione da parte di GestionaleAuto.com, `contattateci e risolveremo il problema <mailto:developers@gestionaleauto.com?subject=[API]%20Errata%20configurazione%20delle%20autorizzazioni>`__                                                                                       |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| 500                | The authorization token provided not properly configured. Please contact GestionaleAuto.com reporting the problem and the token you are currently using              | Vi è un errore di configurazione da parte di GestionaleAuto.com, `contattateci e risolveremo il problema <mailto:developers@gestionaleauto.com?subject=[API]%20Errata%20configurazione%20delle%20autorizzazioni>`__                                                                                       |
+--------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+

.. [#token] Una stringa di 64 caratteri contenenete cifre e lettere

.. This is a workaround to have line break,
   see: http://docutils.sourceforge.net/FAQ.html#how-to-indicate-a-line-break-or-a-significant-newline
.. |br| raw:: html

   <br />