Scopes
Scope is a mechanism to limit an application's access to a user's account. You can consider scopes as permission: a scope is directly related to the permission to perform a specific action on a certain type of resource; in fact, it means that your application will need to require permissions to the user to do something on his data.
The Scopes list works as a whitelist: an Access Token is limited to a certain set of scopes, and an application working on it will be authorized to perform only the actions related to the scopes, and only on the resources indicated.
At the same time, the Access Token is emitted by a user, so it will permit to operate only on the resources owned by the emitter, while the other resources cannot be accessed.
If you are developing an OAuth 2.0 app, you will need to specify the scopes required by your application during the authorization step; the end user will then be presented to the user in the Consent page as a set of required permission that must be granted to the application for its operation. Instead, if your app will use Manual Authentication, the user will decide which scopes to grant when creating the manual token. Keep in mind that in this case, the user is free to choose any scopes he wants, so you need to handle properly the Forbidden errors that could arise due to lack of permissions.
See Authentication for further information.
While selecting the scopes you need to make your application work properly, you should follow the Principle of Least Privilege. This means that you must not select all the scopes, but only those that you absolutely need in your use case. Also, prefer read-only permissions when possible, and require full access only when you need to create, modify or delete a resource.
Enforcing this principle helps keeping the security level high: if some attacker is able to steal an Access Token from your plugin, he'll be able to perform just a limited set of actions on the user's Fatture in Cloud profile. Also, if you require too many permissions, the user could be intimidated or sceptic, and this could result in a failure of the authorization process.
📶 Scope Levels
For the Fatture in Cloud API, the scopes are in the RESOURCE:LEVEL form, where RESOURCE is the kind of resource and LEVEL is the assigned level. The level represents the type of actions that can be performed on the resource.
Our API includes two possible levels:
| Suffix | Level |
|---|---|
| :r | Read-Only Permission |
| :a | Full Write Permission |
Below you can find the complete list of levels that can be associated with the different kinds of resources.
✏️ Scopes List Specification
For the OAuth 2.0 flows, the scopes list is passed as a space-separated list of scopes and is passed in query string (with "scope" key) during the authorization step:
scope=situation:r entity.clients:a issued_documents.quotes:a
The complete URL will be similar to the following (the parameters must be URL-encoded):
GET https://api-v2.fattureincloud.it/oauth/authorize
?response_type=code
&client_id=AwhCk2zoagsNkp3PhRMwYGKzchixuyS2
&redirect_uri=https%3A%2F%2Fredirect-url.com\n&scope=situation%3Ar%20entity.clients%3Aa%20issued_documents.quotes%3Aa
&state=examplestate
🔧 Scopes Toolbox
This is the list of available scopes and levels:
| Scope | Levels | Description |
|---|---|---|
| situation | r | Grants access to dashboard information such as summary cards and deadlines. |
| entity.clients | r, a | Grants access to clients data. |
| entity.suppliers | r, a | Grants access to suppliers data. |
| products | r, a | Grants access to products data. |
| stock | r, a | Grants access to stock data. (Magazzino) |
| issued_documents.invoices | r, a | Grants access to issued documents of type ‘invoice’. |
| issued_documents.credit_notes | r, a | Grants access to issued documents of type ‘credit note’. |
| issued_documents.quotes | r, a | Grants access to issued documents of type ‘quote’. |
| issued_documents.proformas | r, a | Grants access to issued documents of type ‘proforma’. |
| issued_documents.receipts | r, a | Grants access to issued documents of type ‘receipt’. |
| issued_documents.delivery_notes | r, a | Grants access to issued documents of type ‘delivery note’. |
| issued_documents.orders | r, a | Grants access to issued documents of type ‘order’. |
| issued_documents.work_reports | r, a | Grants access to issued documents of type ‘work report’. |
| issued_documents.supplier_orders | r, a | Grants access to issued documents of type ‘supplier order’. |
| issued_documents.self_invoices | r, a | Grants access to issued documents of type ‘self invoices’. |
| received_documents | r, a | Grants access to all types of received documents. |
| receipts | r, a | Grants access to receipts data. (Corrispettivi) |
| calendar | r, a | Grants access to calendar data. (Scadenziario Plus) |
| archive | r, a | Grants access to archive data. |
| taxes | r, a | Grants access to taxes data. (Gestione F24) |
| emails | r | Grants access to emails data. |
| cashbook | r, a | Grants access to cashbook data. (Prima nota) |
| settings | r, a | Grants access to settings. |
If you are the admin of the company that you are using to call our APIs then setting the scopes as explained above is enough, but if you are a sub-user of that company then the admin must assign to you the permissions to access/manipulate the needed resources, for example, if the admin hasn't assigned to you the Fatture e Doc permission (Impostazioni -> Utenti e Permessi) you won't be able to retrieve/create issued documents.