Configuring the OAuth login prompt
If you use Nylas's Hosted OAuth, the first step of the process is to direct your end-users to a login prompt so they can authenticate with their service provider. If your project is available to end users of a large number of service providers, this can look complicated to end-users.
When you direct a user to
api.us.nylas.com/v3/connect/auth, you can pass several query parameters in the URL that change how Nylas displays the login prompt.
Nylas provides the
provider query parameter to allow you to skip the selection process, the
detect provider utility API endpoint, and the
prompt query parameter to allow you to streamline and customize this process.
When you direct a user to
api.us.nylas.com/v3/connect/auth, you can pass the
provider query parameter to allow you to skip or configure the selection process.
If you only have one connector, Nylas skips the user directly to the login prompt for that provider, regardless of the
provider query parameter.
If you already know the end-user's provider, you can pass it as the optional
provider parameter, and Nylas takes the user directly to the login prompt for that specific provider.
If you don't know the end-user's provider you can omit the provider parameter. Nylas then displays a login prompt with an option each of the Google and Microsoft connectors configured for your Nylas application. If the application has an IMAP connector configured, Nylas also displays a View all providers link at the bottom of the login prompt to help users search for a specific IMAP provider.
You can also pass the
provider parameter with a comma separated list of the most-often used providers for your project, and Nylas displays those providers as buttons on the login prompt in the order you specified. IMAP providers do not appear on directly the login prompt unless specified this way, so this is especially helpful if many of your users are on a specific IMAP provider.
You can also configure the login prompt by passing a
prompt query parameter. If you set a
provider query parameter, the
prompt parameter is ignored.
The following options are available:
detect- use the the
POST /v3/providers/detectAPI endpoint to determine the user's provider, and show only that provider.
select_provider- shows the list of providers, even if there is only one connector.
You can also pass both options in a preferred order, for example
prompt=detect,select_provider. This allows you to show the user the list of providers if Nylas is unable to automatically determine their provider.
You can use the
POST /v3/providers/detect API endpoint to query for a provider given a user's email address.
You can also pass
prompt=detect to have Nylas attempt to detect the provider from the login prompt.
IMAP special value that allows you to specify your own config (host/port):