What we need

• [] Client ID
• [] Client Secret
• [] OAuth 2.0 scopes (based on API access needs)
• [] Admin access to Grammarly Enterprise or Education account

Grammarly OAuth2 Integration

This guide provides step-by-step instructions for setting up OAuth 2.0 integration with Grammarly’s REST API for Enterprise and Education customers. For official documentation, refer to Grammarly’s OAuth 2.0 credentials documentation.

Prerequisites

• Admin access to a Grammarly Enterprise or Education institution-wide license
• Not a customer yet? Contact Grammarly sales

Obtaining OAuth 2.0 Credentials

1. Log in to your Grammarly Admin Panel

   • Go to Grammarly Admin Panel
   • Sign in with your admin credentials

2. Navigate to OAuth 2.0 Credentials

   • Open the Organization tab
   • In the Configurations section, select OAuth 2.0 credentials
   • Direct link: OAuth 2.0 credentials

3. Create New Credentials

   • Click the Add credential button in the upper-right corner
   • In the window that appears, enter a descriptive name for your integration
   • Check the box next to the API(s) you will use (see OAuth Scopes section below)
   • Click Create

4. Secure Your Credentials

   • After creation, click Copy to clipboard to save your Client ID and Secret
   • Store these credentials securely as they provide access to your Grammarly account
   • Note: The Client Secret will only be shown once for security reasons

Understanding OAuth 2.0 Scopes

Grammarly’s OAuth credentials use scopes to define specific permissions granted to your application. Select only the scopes necessary for your integration:

Implementing OAuth 2.0 Flow

To implement the OAuth 2.0 flow with Grammarly:

1. Authorization Request

   • Direct users to Grammarly’s authorization endpoint
   • Include your Client ID, requested scopes, and redirect URI
   • Example URL structure:

     https://auth.grammarly.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&scope=scores-api:read&redirect_uri=YOUR_REDIRECT_URI
     

2. Handle Authorization Code

   • After user authorization, Grammarly redirects to your specified URI with an authorization code
   • This code is temporary and should be exchanged for an access token

3. Exchange Code for Access Token

   • Make a POST request to Grammarly’s token endpoint
   • Include your Client ID, Client Secret, authorization code, and redirect URI
   • Example request:

     curl -X POST https://auth.grammarly.com/oauth2/token \
       -d "grant_type=authorization_code" \
       -d "client_id=YOUR_CLIENT_ID" \
       -d "client_secret=YOUR_CLIENT_SECRET" \
       -d "code=AUTHORIZATION_CODE" \
       -d "redirect_uri=YOUR_REDIRECT_URI"
     

4. Use Access Token

   • Include the access token in the Authorization header for API requests
   • Example:

     curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
       https://api.grammarly.com/v1/user/writing-scores
     

Security Best Practices

• Store Client ID and Client Secret securely, never in client-side code
• Implement proper token management (refresh, expiration handling)
• Use HTTPS for all communications
• Request only the scopes necessary for your application
• Implement proper error handling for OAuth flows
• Regularly audit application access and revoke unused credentials

Troubleshooting

• 401 Unauthorized errors: Check that your credentials are correct and not expired
• 403 Forbidden errors: Verify that you have the necessary scopes for the API you’re accessing
• Invalid redirect URI: Ensure the redirect URI matches exactly what was registered
• Rate limiting: Be aware of Grammarly’s API rate limits and implement appropriate backoff strategies

Additional Resources

• Grammarly Developer Documentation
• Writing Score API Documentation
• Analytics API Documentation
• License Management API Documentation