Introduction

Some providers use an OAuth flow to authenticate users on their API.

Using Unipile default configuration will show to your users a consent screen asking permissions to give access to their data to Unipile, not your app. This can be confusing and feel unsafe for the user, making it unsuitable for production-grade applications.

But this screen can show your application name and logo. All you have to do is to register your application with the provider then give Unipile your configuration.

This section is relevant for the following providers only:

Google
Outlook

1. Define your permissions scope

In the OAuth flow, a scope defines the range of permissions an application requests to access data.

To be used, each Unipile method requires specific permissions granted by the account owner. However, before requesting these permissions, the provider must review and approve your application.

When registering your application with the provider, specify the scope of permissions your application will request from users. We recommend limiting the scope to only what is essential for your application's functionality. Refer to the Permissions required list to determine the appropriate scope.

Later, we will see how to restrict the scope requested for individual accounts. However, keep in mind that the scope defined during your application registration represents the maximum set of permissions you can request without submitting your application for another provider review.

2. Register with the provider

Follow our guides to register your application with a provider:

Microsoft for Outlooks accounts.
Google for Google accounts.

3. Configure Unipile

Head to the OAuth tab of your Application, then in the proper provider section :

Collect the Client ID and Client Secret from you application registration and paste them.
Specify the scope of permissions** to match your application registration**. Be careful to do not set permissions that are not declared in your registration as linking an account won't work.

4. Link accounts

Link accounts as usual. The scope of permissions specified in the Settings will be asked to the account owner.

Narrow down the scope

Imagine your registered your application on Google with the full scope of permissions to access the full Emails API and Calendar API. However, if your application only needs access to the Calendar related methods, requesting email permissions may appear unsafe to your users when linking their Google account. To address this, you can limit the scope of permissions on a per-account basis :

Using Create Auth Link or Start Auth Intent, specify the list of permissions in the config.{provider}.oauth_scope or config.oauth_scope field. Make sure to specify only permissions within the scope of your registered application.

Augment scope

If you need to augment the scope of permissions for an account, you can simply force a reconnection of the account with Create Auth Link or Start Auth Intent and give the new list of permissions in the config.{provider}.oauth_scope or config.oauth_scope field. Of course it should be within the scope of your registered application.