> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Grammarly setup

Configview reads your Grammarly organisation through the Grammarly License Management API and Analytics API (`https://api.grammarly.com/ecosystem/api`), using an **OAuth 2.0 credential** that an admin creates in the Grammarly admin panel. Configview sends only read requests. It never creates, changes or removes users or invitations.

You will end up with **2 required secrets** (`GRAMMARLY_CLIENT_ID` and `GRAMMARLY_CLIENT_SECRET`) in Configview when setup is complete.

> **Scope of this integration today.** Configview reads who holds a Grammarly seat (name, work email, admin flag, last activity), pending and expired invitations, the licence summary (seats bought, enrolled, overage, expiry date) and per-person usage counts for the last 30 days (days active, sessions, share of sessions improved, generative AI prompt count). It never reads what anyone wrote: the writing score, AI detection and plagiarism endpoints take document text and are never called, and prompt text is not available or stored.

***

## What you need

* A Grammarly **Enterprise** or **Education** plan with an institution-wide licence. Grammarly states these APIs are for that licence type and they are marked Beta.
* A Grammarly admin to create the credential

***

## Step 1: Open the Grammarly page in Configview

`https://{companyname}.configview.com/admin/integrations/grammarly`

## Step 2: Create the OAuth credential

1. In the Grammarly admin panel open **Organization**, then **OAuth 2.0 credentials**, then **Add credential**
2. Tick only the **Users API** (read) and **Analytics API** (read). Do not tick any write scope or the Scores API
3. Copy the **Client ID** and **Client Secret** now (the secret is shown once)
4. In Configview paste them into `GRAMMARLY_CLIENT_ID` and `GRAMMARLY_CLIENT_SECRET` under **Credentials** and click the save icon

Least privilege: Configview requests the scopes `users-api:read` and `analytics-api:read` only, each script asking for just the one it needs. It exchanges the client credentials for a fresh bearer token on every run, so nothing is written back and nothing rotates.

## Step 3: Connect and verify

1. Click **Connect**. Configview creates its tables and schedules every collector at your default run time:

| Script | Notes |
| - | - |
| **Users** | Seat holders with work email, admin flag and last activity. |
| **Invitees** | Open (INVITED) and lapsed (EXPIRED) invitations. |
| **Licence summary** | Seats, enrolled, expiry date and user-type counts. |
| **Usage (30 days)** | Per-person counts for the 30 days ending two days ago. |

2. Click **Verify now**. The health check reads both secrets, requests a token and calls the licence summary.

If a check fails: **400, 401 or 403** from the token endpoint means the credential was deleted, mistyped or lacks the API. **403** on a read usually means the plan is not Enterprise or Education.

***

## Data Tables

Each table has a `run_at` column. Usage keeps only the newest run; the others keep history.

| Table | Source | Key Columns |
| - | - | - |
| `grammarly_users` | `GET /v1/users` | user\_id, email, name, last\_activity\_at, is\_admin |
| `grammarly_invitees` | `GET /v1/invitees` | invitee\_id, email, name, created\_at, status, is\_admin |
| `grammarly_institution` | `GET /v1/institutions-summary` | institution\_id, seats, enrolled, expiration\_date, admin\_count, active\_count, invited\_count, removed\_count, overage\_seats |
| `grammarly_usage` | `GET /v2/analytics/users/` | user\_id, email, days\_active, sessions\_count, sessions\_improved\_percent, prompt\_count, window\_from, window\_to |

***

## Rate limits

Grammarly documents 50 requests per second per endpoint and asks for exponential backoff on 429. Configview paces at 300 requests per minute, honours `Retry-After` and retries 5xx with backoff. Pages hold up to 250 rows (users, invitees) or 400 (usage).

## Known gaps and things to check on the first run

These come from Grammarly's published API docs; no live tenant has been tested yet.

* **No groups, audit log or webhooks.** Grammarly exposes none of them, so Configview cannot show who changed what.
* **Usage window.** Analytics lags two days, so the 30-day window ends two days ago. A person who joined recently shows low counts.
* **Analytics user id.** Usage rows are joined to the roster by email; the analytics `id` is assumed to equal the user's `user_id`.
* **Licence summary path.** The docs show both `/v1/institutions-summary` and `/institutions-summary`; Configview tries the versioned one first and falls back.
* **Optional fields.** The licence summary omits a user type count when it is zero; Configview stores zero.
* **Last activity.** `last_activity_at` may be empty for people who never used Grammarly; they appear as never active.
* **Token lifetime.** Not stated in the docs; a fresh token is requested every run.

## Things worth knowing

**Seats to reclaim.** People with no activity for 30 days, or zero active days in the usage window, are the first place to look when the licence is full or overage seats appear.

**Admins.** Admins can add and remove users and manage the licence; review admins who have gone quiet.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.