Grammarly User Management API Guide

Auth method: Bearer token (SCIM API token generated in Grammarly Admin Panel)

Setup steps

1. Ensure SAML SSO is fully configured and active for the organization (prerequisite).
2. In the Grammarly Admin Panel, navigate to Settings > SSO & Provisioning.
3. Enable SCIM provisioning to generate a SCIM API bearer token.
4. Copy the bearer token and SCIM base URL; enter both into your IdP (Okta, Entra ID, OneLogin, etc.).
5. Configure attribute mappings in the IdP per Grammarly's documented schema.
6. Activate provisioning in the IdP to begin syncing users.

List Users

• Method: GET
• URL: https://app.grammarly.com/scim/v2/Users
• Watch out for: Filter support (e.g., ?filter=userName eq "...") may be limited; verify with your IdP's SCIM client behavior.

Request example

GET /scim/v2/Users?startIndex=1&count=100
Authorization: Bearer {token}

Response example

{
  "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 42,
  "startIndex": 1,
  "itemsPerPage": 100,
  "Resources": [{"id":"abc123","userName":"user@example.com"}]
}

Get User

• Method: GET
• URL: https://app.grammarly.com/scim/v2/Users/{id}
• Watch out for: Use the Grammarly-assigned id, not externalId, in the URL path.

Request example

GET /scim/v2/Users/abc123
Authorization: Bearer {token}

Response example

{
  "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
  "id": "abc123",
  "userName": "user@example.com",
  "active": true
}

Create User

• Method: POST
• URL: https://app.grammarly.com/scim/v2/Users
• Watch out for: User receives an invitation email. A seat is consumed immediately upon creation.

Request example

POST /scim/v2/Users
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"newuser@example.com",
  "name":{"givenName":"Jane","familyName":"Doe"},
  "active":true
}

Response example

{
  "id": "xyz789",
  "userName": "newuser@example.com",
  "active": true
}

Update User (full replace)

• Method: PUT
• URL: https://app.grammarly.com/scim/v2/Users/{id}
• Watch out for: PUT replaces the full resource; omitting optional fields may clear them.

Request example

PUT /scim/v2/Users/xyz789
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
  "userName":"newuser@example.com",
  "active":true
}

Response example

{
  "id": "xyz789",
  "userName": "newuser@example.com",
  "active": true
}

Update User (partial)

• Method: PATCH
• URL: https://app.grammarly.com/scim/v2/Users/{id}
• Watch out for: Setting active=false deprovisions the user (removes seat); does not permanently delete the account.

Request example

PATCH /scim/v2/Users/xyz789
Authorization: Bearer {token}
Content-Type: application/scim+json
{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
  "Operations":[{"op":"replace","path":"active","value":false}]
}

Response example

{
  "id": "xyz789",
  "active": false
}

Delete User

• Method: DELETE
• URL: https://app.grammarly.com/scim/v2/Users/{id}
• Watch out for: Behavior on DELETE vs. PATCH active=false may differ; Grammarly's docs recommend deprovisioning via active=false through the IdP flow.

Request example

DELETE /scim/v2/Users/xyz789
Authorization: Bearer {token}

Response example

HTTP 204 No Content

List Groups

• Method: GET
• URL: https://app.grammarly.com/scim/v2/Groups
• Watch out for: Group provisioning is only available on Enterprise plans and must be enabled by Grammarly support upon request.

Request example

GET /scim/v2/Groups
Authorization: Bearer {token}

Response example

{
  "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
  "totalResults": 3,
  "Resources":[{"id":"grp1","displayName":"Engineering"}]
}

Get ServiceProviderConfig

• Method: GET
• URL: https://app.grammarly.com/scim/v2/ServiceProviderConfig
• Watch out for: Use this endpoint to confirm which SCIM operations Grammarly supports before building integrations.

Request example

GET /scim/v2/ServiceProviderConfig
Authorization: Bearer {token}

Response example

{
  "schemas":["urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig"],
  "patch":{"supported":true},
  "bulk":{"supported":false}
}

• Rate limits: Grammarly does not publicly document specific SCIM rate limits in its help center.

• Rate-limit headers: Unknown

• Retry-After header: Unknown

• Rate-limit notes: No official rate limit figures published. Follow standard SCIM client best practices (exponential backoff on 429 responses).

• Pagination method: offset

• Default page size: 100

• Max page size: Not documented

• Pagination pointer: startIndex / count (SCIM 2.0 standard params)

• Webhooks available: No

• Webhook notes: Grammarly does not document outbound webhooks for user-management events in its official help center or developer platform.

• Alternative event strategy: Poll SCIM /Users endpoint or rely on IdP-side event logs for provisioning status.

• SCIM available: Yes

• SCIM version: 2.0

• Plan required: Pro (formerly Business) or Enterprise

• Endpoint: https://app.grammarly.com/scim/v2

• Supported operations: GET /Users (list), GET /Users/{id}, POST /Users (create), PUT /Users/{id} (full update), PATCH /Users/{id} (partial update / deprovision), DELETE /Users/{id}, GET /Groups (Enterprise only), GET /ServiceProviderConfig

Limitations:

• SAML SSO must be configured and active before SCIM can be enabled.
• Group provisioning is available on Enterprise plans only and requires enablement by Grammarly support.
• The Business plan has been discontinued and merged into Pro; SCIM is now gated at the Pro tier.
• SCIM token is a static bearer token generated in the Admin Panel; no OAuth token rotation documented.
• Bulk operations are not confirmed as supported.
• No public documentation of filter query support beyond basic userName lookups.
• Supported IdPs with documented guides: Okta, Microsoft Entra ID (Azure AD), OneLogin. Google Workspace is not listed as a supported IdP for SCIM.

For identity graph construction, the SCIM /Users endpoint is the authoritative source for Grammarly user state. Paginate with startIndex and count=100 (default page size) to enumerate all provisioned users; the active boolean field is the canonical signal for seat status - active=false indicates a deprovisioned user whose seat has been freed but whose account data may persist.

Provisioning via Okta: generate the SCIM bearer token, enter the base URL and token into the Okta OIN connector, map userName to email plus givenName/familyName, then assign users to the app. Okta sends POST /scim/v2/Users; Grammarly creates the account and fires an invitation email. Confirm the user appears in the Admin Panel before treating provisioning as complete - email domain verification failures will silently block creation.

Deprovisioning: unassign the user in the IdP; the IdP sends PATCH /scim/v2/Users/{id} with active=false. Grammarly removes the seat. DELETE /Users/{id} behavior diverges from PATCH active=false in undocumented ways - Grammarly's own guidance favors the PATCH path through the IdP flow. For compliance use cases requiring data deletion, confirm retention behavior with Grammarly support separately.

Token rotation is a high-risk operation: regenerating the SCIM bearer token in the Admin Panel invalidates the previous token immediately. Any IdP connector still holding the old token will return 401 and halt all provisioning until updated. Coordinate token rotation with all connected IdP configurations simultaneously.

Provision a new employee via Okta

1. Confirm SAML SSO is active in Grammarly Admin Panel.
2. Generate SCIM bearer token under Settings > SSO & Provisioning.
3. In Okta, add the Grammarly app from the OIN catalog and enter the SCIM base URL and bearer token.
4. Map Okta profile attributes to SCIM fields (userName → email, givenName, familyName).
5. Assign the new employee to the Grammarly app in Okta.
6. Okta sends POST /scim/v2/Users; Grammarly creates the account and sends an invitation email.
7. Verify the user appears in the Grammarly Admin Panel.

Watch out for: If the user's email domain is not verified in Grammarly, provisioning will fail. Verify the domain first.

Deprovision a departing employee

1. In the IdP (Okta/Entra/OneLogin), unassign the user from the Grammarly application.
2. The IdP sends PATCH /scim/v2/Users/{id} with active=false.
3. Grammarly removes the seat from the user; the user loses access.
4. Confirm deprovisioning in the Grammarly Admin Panel under Members.

Watch out for: Deprovisioning removes the seat but may not delete user data. Confirm data handling with Grammarly support if compliance requires deletion.

Rotate the SCIM bearer token

1. In Grammarly Admin Panel, navigate to Settings > SSO & Provisioning.
2. Regenerate the SCIM API token.
3. Immediately update the new token in all IdP SCIM connector configurations.
4. Test provisioning with a non-critical user to confirm connectivity.

Watch out for: The old token is invalidated immediately upon regeneration. Any IdP still using the old token will receive 401 errors and provisioning will halt until updated.

The static bearer token model is the primary operational risk: there is no documented OAuth rotation, no token expiry schedule, and no grace period on regeneration. A token rotation that is not propagated to every IdP connector simultaneously causes an immediate provisioning outage with no fallback.

Group provisioning is gated behind an Enterprise plan and a manual support enablement request - it cannot be activated self-serve even on Enterprise. Teams building identity graph pipelines that depend on group membership data must account for this lead time and the absence of a self-serve toggle.

Grammarly's developer platform (developer.grammarly.com) covers only the Text Editor SDK. There is no documented general-purpose REST API for user management outside of SCIM 2.0. Any automation outside the SCIM contract - including bulk operations and advanced filtering - is unsupported and unconfirmed.

Webhooks are not available; poll /Users or rely on IdP-side event logs for provisioning status signals.