Authentication
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. In the next paragraph, you'll find a flowchart that will guide you in your choice.
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.
🤖 What about machine-to-machine authorization?
Machine-to-machine authorization is the process of ensuring secure communication between individual services, in this case, Fatture in Cloud and your application; this kind of authorization is used between two different backend services, and its main characteristic is that it must exclude human interaction while performing the authorization steps.
For example, some of the use cases that could fall under this category include:
- Performing an API call after receiving a Webhook Notification
- A Cron executed automatically every night to keep the external app in sync with Fatture in Cloud through Polling
In this guide, we consider only the case where an internal system must interact only with your own Fatture in Cloud account; if you need to interact with multiple Fatture in Cloud accounts, and you don't know them at development time, then you should check the diagram above.
As you can notice by reading the descriptions of our authentication methods, none of them seem to be designed to cover this use case, because they all require human interaction at some point:
- The OAuth 2.0 flows all require a human to login and give explicit permissions
- The Manual Token needs to be manually created by humans on the Fatture in Cloud website
Despite that, Manual Authentication is the best solution for this solution: you can store it in your server's environment variables or, even better, in your Secrets Manager, and load it in your application when needed. Human interaction is required only when the token is created, and since it never expires you can continue using it as much as you want.
If you think a never-expiring token could be dangerous, as an alternative you could
perform a manual Key Rotation by generating a new token manually and replacing the
token value on your system, so it will be able to keep working using the new token.
If, instead, you prefer a fully automated method, then you could take advantage of
the Refresh Token emitted by the OAuth 2.0 Authorization Code Flow:
the Refresh Token's expiration time is one year since the last usage, so it means
that if you use the Refresh Token every day to obtain a new Access Token it will
never expire. If you opt for this solution, you should perform the Authorization
Flow once (for example using Postman) to retrieve the Refresh Token, and then store
it as an Environment Variable or as a Secret; every time you need to interact with
our APIs you simply have to retrieve a new Access Token using the stored Refresh
Token, without need for human interaction.
If you think your Refresh Token could be compromised you could always decide to
revoke the old connection and perform a new Authorization Flow, obtaining a new
Refresh token that you can store in your Environment Variable.
🔐 OAuth 2.0 Authorization Code Flow
The OAuth 2.0 Authorization 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.