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

# Grist

> Connect Grist to Oleria to see who has access to your Grist team site: members, team roles, service accounts, and their API keys.

Connect Grist to Oleria to see who has access to your Grist team site: every member and guest, the team role each one holds, and the service accounts that can call the Grist API. Oleria reads this data with the API key of a Grist service account, so the connection doesn't depend on a named person's account, and you can change team access directly from Oleria.

## What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Grist team site:

* **Accounts** - every member and guest of the team site, with their name, email address, team role, and whether they're an owner.
* **Roles** - the team roles **Owner**, **Editor**, **Viewer**, and **Member** (shown in Grist as **No Default Access**), and which accounts hold each one. Guests appear with the **Guest** role.
* **Non-human identities (NHIs)** - Grist service accounts on the team site.
* **Credentials** - the API key Oleria connects with, linked to its service account, with its status. Grist shows other service accounts' keys only to the person who created them, so Oleria doesn't list them. Oleria never reads or stores key values.

Oleria refreshes this data on its [regular sync schedule](https://docs.oleria.com/integrations/overview.md#sync-model).

> [!NOTE]
>
> Oleria doesn't import workspaces, documents, document sharing, or the records inside your documents. This integration covers team-site membership and roles only.

## Prerequisites

* A Grist team site on getgrist.com. Note its subdomain, for example `acme` for `acme.getgrist.com`.
* A Grist user who is an **Owner** of that team site. Only owners can see every member.
* A terminal with `curl`. Grist creates service accounts only through its API.
* A free member slot on the team site. The service account counts as a team member, so if your plan's member limit is reached, Grist rejects it with "No more team members permitted". Remove a member or upgrade first. On paid plans, check with Grist whether it counts as a billed seat.
* Admin access to the Oleria workspace.

> [!WARNING]
>
> A Grist service account belongs to the person who creates it. If that person's Grist account is deleted, the service account and its key are deleted too, and syncs stop. Create it from an account your team will keep, such as a shared admin account.

## Create a service account for Oleria

Grist has no page for service accounts, so you create one with a temporary personal API key, then delete that key.

**1. Create a temporary personal API key**

Sign in to Grist as a team owner. Select your profile picture, then **Account settings** > **Developer**. Under **API Key**, select **Create**.

![Developer page in Grist account settings with the API Key Create button](https://mintcdn.com/oleria/fBKn4sgLr89XA0aa/images/integrations/grist/step-1.png?fit=max\&auto=format\&n=fBKn4sgLr89XA0aa\&q=85\&s=36a31843268bb7e774ae92e81e19ef3c)

Copy the key. You use it only for the next two steps.

Grist allows one personal API key per user. If you already have one, the Developer page shows it instead of a **Create** button. Use that key for the next two steps and skip the last step, so you don't break anything else that uses it.

![Developer page showing the new API key with a Remove link](https://mintcdn.com/oleria/fBKn4sgLr89XA0aa/images/integrations/grist/step-2.png?fit=max\&auto=format\&n=fBKn4sgLr89XA0aa\&q=85\&s=ff7eba6bed4ec838d571acae16ffc950)

**2. Create the service account**

Run this command. Replace `<team>` with your team subdomain, `<personal-key>` with the key you just copied, and set an expiry date. Grist disables the service account's key after that date.

```bash theme={null}
curl -X POST "https://<team>.getgrist.com/api/service-accounts" \
  -H "Authorization: Bearer <personal-key>" \
  -H "Content-Type: application/json" \
  -d '{"label": "oleria-connector", "description": "Oleria integration", "expiresAt": "2027-12-31"}'
```

The response contains `id`, `login` (the service account's address, ending in `@serviceaccounts.invalid`), `key` (its API key), and `expiresAt`. Copy all of them. Grist shows the key only in this response.

> [!NOTE]
>
> Oleria can't see the expiry date, and only the person who created the service account can extend it or replace its key. Before the date passes, sign in as that person and get a personal API key (use their existing one if they have one, as in the first step). Then either extend the date with `PATCH /api/service-accounts/<id>` (body `{"expiresAt": "..."}`), which keeps the current key, or get a new key with `POST /api/service-accounts/<id>/apikey`. That call disables the old key right away, so paste the new one into the Oleria integration straight after. Delete the personal key only if you created it for this.

**3. Make the service account a team owner**

Run this command with the same personal key. Replace `<login>` with the service account's `login` address.

```bash theme={null}
curl -X PATCH "https://<team>.getgrist.com/api/orgs/current/access" \
  -H "Authorization: Bearer <personal-key>" \
  -H "Content-Type: application/json" \
  -d '{"delta": {"users": {"<login>": "owners"}}}'
```

To check, select **Manage team** in Grist. The service account appears in the list with the **Owner** role.

![Manage members dialog with the service account listed as an Owner](https://mintcdn.com/oleria/fBKn4sgLr89XA0aa/images/integrations/grist/step-3.png?fit=max\&auto=format\&n=fBKn4sgLr89XA0aa\&q=85\&s=2ceb279f54d50881b2396213ca08e81e)

Oleria needs the **Owner** role. With any other role, Grist shows only the key's own user, and Oleria rejects the connection.

**4. Delete the temporary personal key**

If you created the key in the first step, go back to **Account settings** > **Developer**, select **Remove** next to the API key, and confirm.

![Remove API Key confirmation dialog](https://mintcdn.com/oleria/fBKn4sgLr89XA0aa/images/integrations/grist/step-4.png?fit=max\&auto=format\&n=fBKn4sgLr89XA0aa\&q=85\&s=23a8304b45b9c5cac50b046e0d916355)

## Permissions Oleria needs

Grist API keys have no scopes. A key acts with its user's team role.

| What you want Oleria to do | What it needs |
| :- | :- |
| Sync members, roles, service accounts, and credentials | A service account with the **Owner** role on the team site. |
| Run remediation actions | The same service account. Oleria uses no separate write credential. |

## Connect Grist to Oleria

**1. Open the integration**

Go to your Oleria workspace, select **Integrations** -> select **Grist**.

**2. Complete the connection form**

Select **Continue** and provide the following:

| Field | Notes |
| :- | :- |
| Team site | Required. Your team subdomain, for example `acme`. You can also paste a team site URL, such as `https://acme.getgrist.com`. |
| API key | Required. The service account's `key` from the create command. |

Oleria stores the API key encrypted.

**3. Confirm the connection**

Select **Authenticate**. Oleria checks that the key is an owner of the team site before it saves anything. Find the newly connected team site on the **Connected** tab of your Oleria **Integrations** page.

> [!NOTE]
>
> When you edit the integration, leave the API key blank to keep the stored one.

## Verify the integration

Confirm the Grist team site appears on the **Connected** tab of your Oleria **Integrations** page with a status of **Healthy**. After the first sync completes, check that your team members and their roles appear in your Oleria workspace, and that the Oleria service account appears as a service account.

## Remediation actions

Oleria can take these actions in Grist. Each one runs with the access of the service account:

* **Create a user.** Oleria invites the email address to the team site with the role you choose, or **Member** if you don't choose one. Oleria never invites a guest or grants **Owner** unless you choose it. Grist sends the person an invitation email.
* **Assign a team role** to a member, for example raise a **Viewer** to **Editor**.
* **Remove a team role.** An owner, editor, or viewer becomes a **Member** (no default access). **Member** is the base team role and can't be removed this way. To take someone off the team site, use **Remove a user from the team site**.
* **Remove a user from the team site.** Grist also deletes all of the person's document and workspace shares. A revert adds them back to the team but doesn't restore those shares.
* **Disable a non-human identity.** The service account is removed from the team site, so its key can no longer reach it.

Keep these limits in mind when you use these actions:

* Oleria reads the team's access list before it changes anything. If the member is already in the requested state, Oleria makes no change.
* Reverting an action restores the member's team role. When a member is removed, Grist also removes their shares on documents and workspaces. A revert doesn't restore those shares.
* Oleria won't change or remove the service account it connects as, and won't remove or demote the team's last human owner.
* Adding a member back sends them a Grist invitation email.
* Guests' access is on documents, so Oleria doesn't change it.
* Oleria can't delete Grist users, revoke another service account's key, or disable an account. Grist allows these only for the account owner or a self-hosted installation admin.

## Known limitations

* **Team-level access only.** Workspaces, documents, document shares, guests' document access, and public links aren't imported yet.
* **No sign-in or activity data.** Grist's API doesn't return when users were created, first signed in, or were last active, and getgrist.com has no audit log API, so Oleria imports no activity.
* **No multi-factor authentication or single sign-on status.** Grist shows two-factor authentication and sign-in method only on each user's own account page, so Oleria reports them as unavailable.
* **Service-account details are visible only to their creator.** Labels, expiry dates, and key status of other service accounts aren't shown to the Oleria service account.
* **Personal API keys aren't visible.** Grist shows a user's personal key only to that user.
* **No groups or custom roles.** Grist team sites don't have them.
* **OAuth isn't supported.** Grist OAuth apps can read documents but not team membership, so Oleria connects with an API key only.
* **getgrist.com team sites only.** Self-hosted Grist and custom team domains aren't supported.
* **Renaming the team subdomain breaks the connection.** The connection is tied to the subdomain you entered. If an owner changes it in Grist, syncs fail. Remove the integration and add it again with the new subdomain.

## Contact us

For questions about this integration, contact us at [support@oleria.com](mailto:support@oleria.com).


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