Receive OAuth 2.0 credentials – Grammarly Support

Who has access: Grammarly Enterprise and Grammarly for Education admins

Grammarly API uses OAuth 2.0 protocol for secure integration with third-party applications.

To receive OAuth credentials for your application, follow these steps:

Go to your Admin panel.
Open the Organization tab and choose OAuth 2.0 credentials in the Configurations section:
On the next page, click Add credential in the upper-right corner.
In the window that appears, enter a name and check the box next to the API you will use.
Click Create.
Next, click Copy to clipboard to save your Client ID and Secret.

Overview of OAuth scopes

Grammarly’s OAuth credentials can be assigned OAuth scopes, which are features that define the specific permissions granted to an OAuth client when accessing the Grammarly API. OAuth scopes limit access to only necessary resources, enhancing security by minimizing granted permissions.

Each OAuth client can be assigned the following scopes:

scores-api:read

Provides read-only access to the Writing Score API, allowing applications to retrieve writing scores for submitted text.

Suitable for applications that evaluate or analyze text quality, offering insights like writing clarity, engagement, and overall score.

scores-api:write

Provides write access to the Writing Score API, enabling applications to submit documents for writing score evaluations.

Suitable for applications that evaluate or analyze text quality, offering insights like writing clarity, engagement, and overall score.

analytics-api:read

Grants read-only access to the Analytics API, which provides Grammarly usage statistics for team plan members, including metrics like the number of writing sessions, the percentage of improved writing sessions, and generative AI prompt usage.

This scope is commonly used by BI applications or analytical dashboards that show engagement with Grammarly.

Authenticating using OAuth credentials

The examples below demonstrate how to authenticate a client and make API requests to Grammarly using OAuth credentials.

1. Authenticating with OAuth to obtain an Access Token

To authenticate, use the Client ID and Client Secret to request an Access Token from Grammarly’s OAuth server. This token is required for all subsequent API calls.

In this example, we’ll use a curl command in bash to request an Access Token. This example uses the jq tool to parse JSON responses. You can install jq by running sudo apt-get install jq on Ubuntu and Debian or brew install jq on macOS.

# Define your client credentials and API endpoint
CLIENT_ID="your_client_id"
CLIENT_SECRET="your_client_secret"
TOKEN_ENDPOINT="https://auth.grammarly.com/v4/api/oauth2/token"
SCOPE="users-api:read, users-api:write" # string with comma separated scopes

# Use curl to make a POST request to obtain an access token with the specified scope
response=$(curl -s -X POST "$TOKEN_ENDPOINT" \
  -d "grant_type=client_credentials" \
  -d "client_id=$CLIENT_ID" \
  -d "client_secret=$CLIENT_SECRET" \
  -d "scope=$SCOPE")

# Extract the access token from the response
ACCESS_TOKEN=$(echo $response | jq -r .access_token)

Important: To avoid exposing sensitive information in your scripts, always store your Client ID and Client Secret as environment variables or in a secure location.

2. Making an authenticated API request using an Access Token

Once you have an Access Token, you can use it to make requests to the Grammarly API.

Here’s an example of fetching user data from the Analytics API using the retrieved token:

# Define the API endpoint for the user data
USER_DATA_ENDPOINT="https://api.grammarly.com/ecosystem/api/v2/analytics/users?limit=10&date_from=2024-10-01&date_to=2024-10-31
# Make a GET request to the API with the access token
user_data=$(curl -s -X GET "$USER_DATA_ENDPOINT" \
  -H "Authorization: Bearer $ACCESS_TOKEN")

# Output the user data
echo "$user_data"

Available APIs