To make requests towards the Fatture in Cloud API it is necessary to use one of the supported authentication methods. You should choose the method that better suits your use case.
The currently supported methods are:
Below you can find a more detailed descriptions of those flows.
🙋♀️ Which authentication should I use?
Below you can find a useful diagram to help you choose the Authentication Method that best fits your needs. If it is still not enough to choose the best authentication flow for your use case, then please contact us.
Here's an explanation of the different steps:
Are you just testing our APIs? If you just want to try our APIs, or if you want to start implementing the code to manage them delaying the Authorization steps implementation, then the best way is to use the Manual Authentication: you'll be ready in a few minutes.
Are you writing a one-time script (for example initial load)? If your script is meant to be used just one time for an exceptional task, such as the initial load of data into Fatture in Cloud, then it doesn't make sense to take care of the implementation of a complex authorization method. Also, you will likely run your script locally (without web interaction) and you'll use a very limited set of Fatture in Cloud accounts (maybe just your own). In this case, we suggest the Manual Authentication.
Do you need multiple Fatture in Cloud users to use your app? If you're developing a public application, that will potentially be used by big amount of users with different Fatture in Cloud accounts, then you'll almost surely need a proper Authentication/Authorization flow. If that's not the case, and you need to manage just one Fatture in Cloud account (or maybe a limited known set of accounts), then the Manual Authentication could be the best solution for you.
Can you safely store a secret? (e.g. does your app have a backend?) In the most common case of a public web app or plugin, that must be used by an unknown set of users with different Fatture in Cloud accounts, then you need to implement one of the two supported OAuth 2.0 flows. If your application can safely store a secret, usually because it is used by a backend application without sharing it with the end-user, then the OAuth 2.0 Authorization Code Flow is strongly suggested, because it introduces an additional layer of security with respect to the other flows. Alternatively, if you can't store a client safely (for example because you're developing a frontend application or a plugin) then the OAuth 2.0 Device Code Flow can be used to keep a good User Experience.
Can you manage the redirect? (e.g. can your app expose a public endpoint?) To use the OAuth 2.0 Authorization Code Flow you must be able to perform a redirect to an endpoint exposed by your backend. If you're not able to do that, for example, because you don't have a backend, or because you're developing a plugin or a desktop application, then the Authorization Code is not for you. In this case, we suggest using the OAuth 2.0 Device Code Flow.
In summary: The OAuth 2.0 Authorization Code Flow is the preferred authentication method for our API. We strongly recommend using it by default. Only if you can’t implement an Authorization Code Flow for your app (for example if you can’t safely store the client secret), or if you want to develop a script or an app for private use, then the OAuth 2.0 Device Code Flow or even the Manual Authentication methods could be useful.
🔐 OAuth 2.0 Authorization Code Flow
The OAuth 2.0 Authentication Code Flow is one of the Flows specified in the OAuth 2.0 standard.
With this method, the user will be redirected to a dedicated Fatture in Cloud web page, where he will log in and give an explicit approval or denial to the permissions needed by the application.
The user will then be automatically redirected back to the app page; in case of approval of the permissions request the application will be authorized to interact with the Fatture in Cloud APIs.
A detailed description of the Authorization Code Flow can be found on the standard specification page; we also prepared a more specific explanation of our implementation of the flow, where you can also find useful code examples.
The Client Secret, used in the OAuth 2.0 flow, is a piece of sensible information so it must NEVER be shared with third-party actors, and it must always be kept safe (for example in an environment variable used by your backend). Never share it with other people, or publish it on your frontend! If it happened, then we suggest you to delete your application on the Fatture in Cloud page.
📱 OAuth 2.0 Device Code Flow
The OAuth 2.0 Device Code Flow is one of the Flows specified in the OAuth 2.0 standard.
The OAuth 2.0 Device Code flow is not generally available. We're activating it on request, and only for specific use cases that must be approved by our team, for example because the other flows are not appliable. Please, feel free to contact us if you want to use this flow.
This method is similar to the Authorization Code Flow described above, but in this case, the user will not be redirected by the application, that will instead display a code and a link: the user will need to manually open the link and insert the code before giving his permissions.
In the meanwhile, the application will start polling for the result: when the user will approve the result, the app will receive the token and the application will be enabled to interact with our APIs.
A detailed description of the Device Code Flow can be found on the standard specification page; we also prepared a more specific explanation of our implementation of the flow, where you can also find useful code examples.
✋ Manual Authentication
Manual Authentication is an alternative method that uses an access token provided by the user; it thus requires a higher level of interaction by the user who will be required to:
- Associate your application to his Fatture in Cloud account;
- Manually select the permissions that must be granted to your application;
- Provide the generated token to your application.
Unlike the OAuth method, in this scenario the user can decide which permissions must be granted to the token, so you will have to inform the user about the scopes that your app needs. He can also decide on which of its companies the generated code will be valid.
There are two main drawbacks of this approach:
- This authorization flow is less secure (the token never expires);
- The user experience is impacted (it requires the user to perform some manual operations on the Fatture in Cloud web app).
For the aforementioned reasons, we suggest using this authentication method only for private apps or when it is not possible to adopt one of the more secure authentication methods.
Keep in mind that in this scenario the user is free to provide the scopes he prefers (it's not the app that asks the user the permissions it needs to perform its operations), so your app will have to correctly manage possible errors that could arise due to lack of permissions.
Access Tokens generated with this method work exactly as OAuth 2.0 Access Tokens, but they don’t have an expiration so you won’t need to refresh them. Keep in mind that the user is free to revoke the token whenever he wants.
✅ How should I select the auth flow I chose?
Once you figured out the authentication method that better suits your application you have to select it by going to your account settings in the Fatture in Cloud website and clicking on the Gestisci button. The app page will look similar to the following image:
You can select the method that you want to use by selecting the ones you want to activate for your application (in the image only the OAuth 2.0 method is selected) and clicking the Salva button; you can select both the auth methods for a single app.
On the app page, the OAuth 2.0 option refers only to the OAuth 2.0 Authorization Code Flow. The Device Code Flow is not generally available (as stated previously), so it won't appear on this page, even after manual activation by the API team.