IMPORTANT: This documentation has been discontinued. Read the updated New Oauth2 Architecture documentation on our new documentation portal.
The OAuth2 is a standard protocol for authorization commonly used for web APIs. To create integrations that use OAuth2, just log into a provider - which could be Google, Microsoft, Mercado Livre, Amazon, etc. - and receive an access token. Through this token, it is possible to access users' data without having to inform their credentials.
To add it to our platform, it is necessary to previously create an application on the provider you want to use. Once the application is created in the provider, it will be possible to register and use the OAuth2 protocol on the Digibee platform.
1. Registering a new OAuth provider from an existing one
To create your application, follow the instructions according to the provider you want to add to the Platform by clicking on the links below:
In the Redirect URI field, you will need to use the following address:
Once the application is created, you will have the Client ID and Client Secret, which are the OAuth authentication keys that must be informed during the creation of the new provider, in a new Account within the Digibee Platform (read the tutorial at the end of this article).
2. How do token requests work?
In order to explain how to obtain the token, we will use the Google flow, which is the same for all OAuth2 providers that follow the Code Grant Type flow:
The first step is to request an intermediate token. This occurs when the user, during login, accepts the scopes and consents to the use of their data;
After the user consents, an intermediate token (named code) is generated and will be used to return the access token, which is the final token;
With the access token in hand, it is possible to make requests to the provider's services.
3. How does token lifetime work?
The access token expiration time is given by the expires_in property. For example, the value "7200" denotes that the access token will expire in two hours from the time the response was generated.
Concerning providers registered by Digibee, we have the following expiration times:
6 months duration for Google and Mercado Livre;
3 months duration for Microsoft.
IMPORTANT: It is necessary to log in again to the accounts screen after the refresh token expires.
4. What to do if the refresh token is not returned?
The refresh token may not return for a variety of reasons, but often the cases where it is not returned are due to an excessive number of logins. If your new account has not been saved by the refresh token, you must remove the OAuth2 app from your email account following the guidelines of the provider used to log in to the Platform.
To find out how, visit the link below:
After that, you need to log in to the provider through the Digibee Platform again and, finally, save your account.
5. Learn how to request new providers
To request a provider that is not on our list, contact us through the Digibee Platform chat. Then, we will be able to add it manually.
6. Learn how to use the token in the pipeline
Once the oauth-2 account is created on the Platform, just use it in the Account field by selecting the Rest V2 connector on the canvas. It is also necessary to inform the URL of the service to be requested, headers, and query parameters necessary for the request to be made using the generated access tokens.
Examples of requests:
Requesting Google Drive File Listing API in Rest V2 component:
Requesting OneDrive File Listing API in Rest V2 component:
Requesting the API that returns information about your Mercado Livre account:
IMPORTANT: Once the previously created OAuth account is informed in the Account field of the Rest V2 component, the Authorization header will be automatically added.
Once the application is created, it will be possible to register your new OAuth2 provider on the Digibee Platform following the tutorial in Registration of new providers.