Organizations

Grain is multi-tenant: each church is an organization. OAuth access tokens require X-Organization-Id so Grain knows which church’s data to return. Organization API keys already identify one organization, making the header optional.

Header format

X-Organization-Id: cm123abc456def

The value is a UUID-style organization ID (CUID in Grain’s database). With an API key, including a different organization ID returns 403; a key can never be used to switch organizations.

How users get an organization ID

When a user signs in to Grain, they may belong to one or more churches. Your OAuth flow authorizes the user, not a specific organization. Your application chooses which organization to access per request.

If your integration serves a single church, store the organization ID after the user selects their church in your onboarding flow.

Finding the ID in the Grain app

Sign in at app.grainledger.com
Open the organization switcher (top of the sidebar)
The organization ID is available in organization settings or from your Grain contact during API onboarding

If you are building a partner integration, the Grain team provides the organization ID when API access is approved. Request API access.

Multi-organization OAuth users

A single user can be a member of multiple churches (for example a bookkeeper serving several clients). Your application should:

Let the user pick which church to work with
Send that organization’s ID in X-Organization-Id on every request
Switch the header when the user changes churches

Permissions are evaluated per organization. A user with admin access at Church A may have read-only access at Church B.

Example

curl -X GET "https://api.grainledger.com/api/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "X-Organization-Id: cm123abc456def"

const organizationId = userSelectedOrgId; // from your app's org picker

const response = await fetch(
  "https://api.grainledger.com/api/v1/transactions?page=1&limit=20",
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      "X-Organization-Id": organizationId,
    },
  }
);

Authentication for OAuth setup
Errors for 400 and 403 responses when the header is missing or invalid

Last modified on July 13, 2026

Overview

Core concepts

Header format

How users get an organization ID

Finding the ID in the Grain app

Multi-organization OAuth users

Example

​Header format

​How users get an organization ID

​Finding the ID in the Grain app

​Multi-organization OAuth users

​Example

​Related

Header format

How users get an organization ID

Finding the ID in the Grain app

Multi-organization OAuth users

Example

Related