Introduction

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

Using Unipile’s default configuration will show your users a consent screen displaying Unipile’s name and logo. But this screen can show your application name and logo. All you have to do is register your application with the provider and 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

Open Configuration → OAuth in your Application, choose Custom in the relevant provider section, then:

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.

Change the scope of an existing account

To change the permissions of an existing account, reconnect it with Create Auth Link or Start Auth Intent and pass the final list of permissions in config.{provider}.oauth_scope or config.oauth_scope. The account can be running, partially connected, or disconnected. Reconnecting refreshes the entire account and restarts all configured products.

If oauth_scope is omitted when reconnecting, permissions already granted are preserved and the permissions currently configured in the Provider OAuth settings are added. Any permissions you explicitly provide must remain within the scope of your registered application.

Manage OAuth configuration in the Dashboard

Open Configuration → OAuth and choose a mode for Google or Microsoft Outlook:

Default uses Unipile's shared provider application. It displays Unipile's name and can be used in production. The shared Google application supports email and calendar methods, but not contacts methods.
Custom uses the provider application you registered, with your Client ID, Client Secret, and authorized permissions.

You can select the supported Methods scopes in either mode. In Default mode, the available set is limited to the shared application's supported permissions. Auth scopes needed to identify the account are added automatically and displayed separately. See Permissions required.

Save credentials or permission changes

Select the mode and, for Custom, enter the Client ID and Client Secret.
Select the Methods scopes your integration needs.
Save the settings.
Review and confirm the displayed impact on existing accounts.

Changing the OAuth application, Client ID, or Client Secret may cause existing accounts in this Unipile application to disconnect when their current tokens expire. Reconnect affected accounts using the new configuration. Accounts in other Unipile applications are unaffected.

Changing the default Methods scopes affects future connection requests. Existing accounts retain the permissions already granted. Removing a scope here does not revoke it on an existing account. Reconnect that account with the intended final permission list to request changed consent.

Return to Default

Select Default, review the reset warning, and save. Previously saved custom credentials and unsupported custom scopes are reset. Accounts connected with your custom OAuth application may need reconnection to use Unipile's shared application.

Choose permissions for one connection

Use Advanced Authentication to choose Application configuration or a custom subset for one link. For an existing account, open its actions menu and choose Re-authenticate to review the final selection.

The account detail page shows its granted OAuth permissions. These may differ from today's application defaults. OAuth permissions are separate from account isolation Scopes and the informational Consent scopes shown by Hosted Auth.