GitHub CommunityYouTubeTwitchTwitterSupport
Docs/Connected Accounts

Connected Accounts

The connected accounts feature allows users to connect their Grammarly accounts to your application so that they can access full account features and suggestions, such as their personal dictionary, style guide, and customization preferences.

How it works

Grammarly implements the industry-standard OAuth 2.0 protocol to securely issue access tokens for third-party applications.

  • Once the connected accounts feature is turned on for your application, users will start seeing the "Connect your Grammarly Account" menu option under the Grammarly button.

  • After clicking "Connect your Grammarly Account," the user will see the consent screen, which will ask the user to authorize your application to interact with their Grammarly account. The consent screen is a crucial part of the standard OAuth 2.0 flow.

  • Once the user approves the application, the Grammarly Text Editor SDK receives a long-term session token that is stored in the localStorageopen in new window of your application. The session token gets automatically renewed each time a user interacts with Grammarly through the Text Editor SDK from within your application.

    The session token expires after 30 days of inactivity. When the token expires, the user will be offered to reconnect their Grammarly account to your application. When a user reconnects, they will not be asked for consent again if they have approved your app previously.

  • A user can log out of their Grammarly account from your application by choosing the “Log out” menu option under the Grammarly button. If they choose to connect their Grammarly account again, the consent screen will be skipped, as the user already authorized your application in the past.

A user may use your application from multiple browsers. Each browser would maintain its own connection state, as the session token is saved in localStorage that is not shared between different browser instances. However, a user will only need to approve the application via the consent screen once for your application, as the user’s consent is shared between sessions.

Grammarly Button

Turning on connected accounts

You can turn on and set up this feature from your App Console in the Connected Accounts section. For desktop clients only, there are a few more steps required to support the user authorization flow, described below.

You can customize the way your application is shown to users publicly by setting a display name, a developer name, and an app logo.

The names and assets that you specify here should be wholly your own—this information will be displayed to users on the consent screen that asks users to connect their Grammarly account. For more information, see Naming and describing your application.

Privacy policy

Please note that you’ll need a privacy policy that states your commitment to your customers. This would be in addition to Grammarly’s own privacy policy, which does not cover your application’s privacy practices.

Personal dictionary

Once connected accounts is turned on for your application, if a user chooses to connect their Grammarly account, that user will be able to add unique words, or stop flagging a particular spelling of a word as incorrect, in their personal dictionary.

Personal dictionary

Users can manage their personal dictionary by signing in to their account, navigating to Account, and then selecting Customizeopen in new window. For more information, including instructions on how to add and remove words from a dictionary, see How do I use my personal dictionary?open in new window

Note that the personal dictionary feature is different from the application dictionary feature. Dictionaries for applications are created and managed in the App Console and apply to anyone using your app.

Configuring connected accounts for desktop clients (Electron)

The instructions below are for desktop clients only. For a web client, you don't need to perform any of these additional steps—simply turn on connected accounts for your application.

Allowing users to connect their Grammarly accounts to your desktop application requires a few extra steps. The instructions below will guide you through this process. They include code snippets and pseudocode you can use to get started. Complete examples are available in the Grammarly for Developers GitHub repositoryopen in new window:

Before you begin: Ensure you have a desktop application that includes a renderer script with at least one text field successfully using the Grammarly Text Editor Plugin. See Text Editor SDK for Electron for detailed instructions.

Add a list of redirect URIs to your client configuration

Grammarly needs to know which URIs it can redirect to after a user attempts to connect their Grammarly account to your application. You will need to provide these redirect URIs in the App Console. Please see Redirect URIs (desktop clients) for more information.

Turn on connected accounts for your Electron app

Next, you'll need to turn on connected accounts so that users will see the “Connect your Grammarly account” option when they click the Grammarly Button in your application.

The Grammarly button menu that includes an option to 'Connect your Grammarly account'
  1. Open the App Console by going to My Appsopen in new window and selecting your application. Then select Connected Accounts in the left menu.
  2. Select Allow connected accounts with OAuth 2.
  3. Input the app's display name, developer name, homepage URL, and privacy policy URL.
  4. Optionally, upload a logo.
  5. Click Save.

TIP

Only alphanumeric characters, symbols like - (hyphen), ’ (apostrophe), , (comma), + (plus), and the blank space are allowed in the display name and developer display name.

Include the oauthRedirectUri configuration for the Text Editor Plugin

To use connected accounts, you’ll need to specify the oauthRedirectUri property of the EditorConfig for the Text Editor Plugin. The oauthRedirectUri must be in the list of redirect URIs in your desktop client credentials (see the section above).

Example code for configuring the plugin for a textarea to have an OAuth redirect URI of "example://grammarly-auth" is below.

<grammarly-editor-plugin config.oauthRedirectUri="example://grammarly-auth">
  <textarea></textarea>
</grammarly-editor-plugin>

When a user selects "Connect your Grammarly account," they’ll be taken to a URL to log in on grammarly.com. It’s important to ensure that this URL is opened in a web browser, rather than inside the app. Here’s an example of code that could be included in your main script:

win.webContents.setWindowOpenHandler(({ url }) => {
  if (url.includes("grammarly")) {
    shell.openExternal(url); // open the link in Electron system's default browser
    return { action: "deny" }; // don't open the link in Electron app
  } else {
    // these are not Grammarly links, so they can be opened within Electron app
    return { action: "allow" };
  }
});

Set your app as the default protocol client for your redirect URI

For any redirect URIs specified earlier, you’ll need to set your app as the default protocol client. This will ensure that, when the OAuth flow completes, the URI will be opened inside of your desktop app.

To do so, include a line like the following in your main script:

app.setAsDefaultProtocolClient("example");

Add an event listener for open-url events in your main process

After a user successfully authenticates on grammarly.com, Grammarly will call the redirect URI you specified in the editor config. Your desktop application should listen for open-url events and pass the URL associated with the event to a renderer process that is using the Text Editor SDK.

There are a variety of ways to listen for events in the main process and pass the associated URL to a renderer process. The psuedocode below listens for open-url events and checks if the URL matches a Grammarly redirect URI that was configured for this desktop application in My Appsopen in new window.

app.on("open-url", (event, url) => {
  // If the link matches a Grammarly redirect URI, send the link to the renderer process
  if (url.includes("grammarly-auth")) {
    event.preventDefault();

    // Add your messaging code here to send the link to your renderer process
  }
});

Pass the URL to the Text Editor SDK

The final step in the OAuth flow is to pass the URL from the open-url event to the EditorSDK in your renderer script. This is done by calling handleOAuthCallback inside a renderer script.

For instance, in your code that handles receiving messages from the main process, you could include code like the following:

const grammarly = await init("YOUR_CLIENT_ID");
grammarly.handleOAuthCallback(url); // this URL is passed from the main script as described in the previous step

Summary

Now you’ve configured connected accounts for your Electron app! Users can click the Grammarly button in your app, select the option to connect their account to your application, and access full account features and suggestions.

Complete examples are available in the Grammarly for Developers GitHub repositoryopen in new window:

Learn more about enabling Grammarly suggestions in the guide for using the Text Editor SDK in Electron apps.

Last Updated: 6/28/2023, 9:00:14 PM
Rate this page