Set up white-labeling in Nylas
Nylas v3 allows you to customize (or "white-label") parts of the end user authentication experience so they see your company's branding instead of the Nylas logo and domain. This page explains how to set up white-labeling for Hosted authentication.
Nylas provides a login page for Hosted authentication that displays the Nylas logo by default. This tells the user knows who is requesting access to their account. However if the user isn't expecting the Nylas logo or domain, this might worry them enough that they stop the authentication process.
You can upload your own icon for the user-facing Hosted OAuth page for any application so that it appears on this login screen. The Nylas domain (nylas.com
) might still appear during in the OAuth process. If you're on a paid tier that includes it, you can replace these by white-labeling your Hosted OAuth domain.
![The default Nylas Hosted OAuth login page.](/_images/auth/hosted-auth-login.png)
💡 If you want to further customize the auth experience, you can build your own authentication system, then use Custom authentication to authenticate users.
Add your logo to Hosted OAuth
You can add a custom logo either using the v3 Dashboard, or using the Update application API. This is available to all users, regardless of plan tier.
To upload a new logo for the Hosted auth login page:
- Log in to the v3 Nylas Dashboard and select the application you want to work with.
- Select Hosted authentication in the left navigation.
- Enter a link to your logo in the Icon URL field.
🔍 Your icon must be a PNG, JPG, or TIF file, and 1MB or smaller. Nylas also resizes the logo to 72x72 pixels, so make sure it's a square image.
- Save your changes.
Replace the Nylas domain using custom whitelabeling
By default Nylas uses the nylas.com
domain in the OAuth process even if you replace the Nylas logo. If users don't expect to see "Nylas" during authentication, they might stop the process on security grounds. To prevent this, you can set up a white-label domain, so that your own domain appears instead during authentication.
To completely remove the Nylas branding and domain from hosted authentication:
- Subscribe to a Nylas plan that includes White-labeled Hosted Auth.
- Add your preferred logo (as described above).
- Set up a DNS A record for the URL you want to use.
- Update your provider auth apps to allow auth from your A record address.
- Contact Nylas Support to activate your domain.
Set up a DNS A record
Set up a DNS A record for the URL you want to use for authentication, for example, auth.example.com
. This is where you start user authentication requests, and for users authenticating using a web browser, this URL might appear in the URL bar, so make sure your domain is clearly included.
This URL should forward traffic either to 34.102.247.196
for U.S. applications, or to 34.149.152.232
for E.U. applications.
Update provider auth applications
Next, add your authentication URI to your provider auth applications as an allowed redirect URI. You can either make this an additional redirect URI, or use it to replace the Nylas redirect URI.
For example, you might have api.us.nylas.com/v3/connect/callback
already configured as a redirect URI, and you could replace it with auth.example.com/v3/connect/callback
.
- For Google: Log in to your GCP app, select Credentials in the left navigation and update the appropriate credential record.
- For Azure: Log in to your Azure app, search for App registration, navigate to the resulting page, and update the Redirect URI.
Activate your domain
Submit a ticket to the Nylas Support team who will confirm your plan and activate white-labeling.
Using white-labeled authentication
Once you set up and enable white-labeling, you access hosted authentication using the same API methods, but replacing the Nylas API route with your own custom domain.
For example, you might have a URL to start authentication that looks like this:
https://api.us.nylas.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&redirect_uri=<https://myapp.example.com/callback-handler>&response_type=code&provider=google
And using white-labeled authentication it would be:
https://auth.example.com/v3/connect/auth?client_id=<NYLAS_CLIENT_ID>&redirect_uri=<https://myapp.example.com/callback-handler>&response_type=code&provider=google