Organizations

Grain is multi-tenant: each church is an organization. Most 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. Grain-managed OAuth apps may omit the header only on GET /api/v1/organizations.

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.

Organization discovery for Grain-managed apps

Grain-managed OAuth apps can list churches the current user has an active grant for:

curl "https://api.grainledger.com/api/v1/organizations" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

The response includes only organizations with an active grant for this client_id and user. It does not list every membership. Unmanaged OAuth clients and API keys cannot call this endpoint.

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

Overview

Core concepts

Header format

How users get an organization ID

Organization discovery for Grain-managed apps

Finding the ID in the Grain app

Multi-organization OAuth users

Example

​Header format

​How users get an organization ID

​Organization discovery for Grain-managed apps

​Finding the ID in the Grain app

​Multi-organization OAuth users

​Example

​Related

Header format

How users get an organization ID

Organization discovery for Grain-managed apps

Finding the ID in the Grain app

Multi-organization OAuth users

Example

Related