Skip to main content
Grain is multi-tenant: each church is an organization. Every API request must include the X-Organization-Id header so Grain knows which church’s data to return.

​
Header format

X-Organization-Id: cm123abc456def
The value is a UUID-style organization ID (CUID in Grain’s database).

​
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

  1. Sign in at app.grainledger.com
  2. Open the organization switcher (top of the sidebar)
  3. 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 users

A single user can be a member of multiple churches (for example a bookkeeper serving several clients). Your application should:
  1. Let the user pick which church to work with
  2. Send that organization’s ID in X-Organization-Id on every request
  3. 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 8, 2026