Skip to main content

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.

Don't catch them all!!!

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:

SuffixLevel
:rRead-Only Permission
:aFull 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:

ScopeLevelsDescription
situationrGrants access to dashboard information such as summary cards and deadlines.
entity.clientsr, aGrants access to clients data.
entity.suppliersr, aGrants access to suppliers data.
productsr, aGrants access to products data.
stockr, aGrants access to stock data. (Magazzino)
issued_documents.invoicesr, aGrants access to issued documents of type ‘invoice’.
issued_documents.credit_notesr, aGrants access to issued documents of type ‘credit note’.
issued_documents.quotesr, aGrants access to issued documents of type ‘quote’.
issued_documents.proformasr, aGrants access to issued documents of type ‘proforma’.
issued_documents.receiptsr, aGrants access to issued documents of type ‘receipt’.
issued_documents.delivery_notesr, aGrants access to issued documents of type ‘delivery note’.
issued_documents.ordersr, aGrants access to issued documents of type ‘order’.
issued_documents.work_reportsr, aGrants access to issued documents of type ‘work report’.
issued_documents.supplier_ordersr, aGrants access to issued documents of type ‘supplier order’.
received_documentsr, aGrants access to all types of received documents.
receiptsr, aGrants access to receipts data. (Corrispettivi)
calendarr, aGrants access to calendar data. (Scadenziario Plus)
archiver, aGrants access to archive data.
taxesr, aGrants access to taxes data. (Gestione F24)
emailsrGrants access to emails data.
cashbookr, aGrants access to cashbook data. (Prima nota)
settingsr, aGrants access to settings.
I added the correct scopes but I'm still getting a 403 NO PERMISSION error

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.

📚  Additional resources