Authentication

The Grain API supports two authentication methods:

Organization API keys for server automation owned by one church. This is the fastest way to test the production API.
OAuth 2.1 (Sign in with Grain) for applications that act on behalf of individual users, especially apps serving multiple organizations.

REST API and MCP access require an active Enterprise plan for the organization you are accessing.

Store API keys, access tokens, and refresh tokens in a secrets manager. Never expose credentials in client-side code, logs, or public repositories.

Organization API keys

An Owner, Admin, or custom role with Manage API access can create a key in Settings → API. Give the key a descriptive name, choose the smallest required scope set, and select an expiry. The secret is displayed only once. Production organizations receive keys beginning with grain_live_. Sandbox, demo, and test organizations receive grain_test_ keys.

curl "https://api.grainledger.com/api/v1/transactions?page=1&limit=20" \
  -H "Authorization: Bearer grain_live_YOUR_KEY"

The key determines its organization, so X-Organization-Id is optional. If you include the header, it must match the key’s organization. API keys work only under /api/v1; they cannot sign in to the Grain app, call tRPC or MCP, or authenticate directly with the identity provider.

API key scopes

Resource	Read	Write
Transactions	`transactions:read`	`transactions:write`
Bills	`bills:read`	`bills:write`
Donors	`donors:read`	`donors:write`
Contributions	`contributions:read`	`contributions:write`
Pledges	`pledges:read`	`pledges:write`
Households	`households:read`	`households:write`
Pledge card imports	—	`pledge-cards:write`

Write access includes the corresponding read access. Donor and household scopes can expose personal information. Contribution and pledge responses include donor IDs but never embed donor identity; use a donor read scope to retrieve the related donor separately.

Rotation and revocation

Rotating a key displays a new secret once. The previous secret remains valid for up to 24 hours, or until its original expiry if sooner, so you can update automation without downtime. You can revoke the previous secret immediately after deployment. Full revocation permanently disables both secrets; the named key stays visible for audit history.

OAuth 2.1 flow

Redirect to authorize

Send the user to https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/authorize with your client ID, redirect URI, scopes, and PKCE parameters (code_challenge and code_challenge_method=S256).

User consents

The user signs in (if needed) and approves access at https://app.grainledger.com/oauth/consent.

Receive authorization code

Grain redirects back to your redirect_uri with an authorization code and state parameter.

Exchange for tokens

POST the code to https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/token with your code_verifier to receive access and refresh tokens.

Call the API

Include Authorization: Bearer <access_token> and X-Organization-Id on every API request.

OAuth endpoints

Purpose	URL
Authorization	`https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/authorize`
Token	`https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/token`
Consent UI	`https://app.grainledger.com/oauth/consent`
OAuth discovery	`https://pqnoojlycpbwbatbdgep.supabase.co/.well-known/oauth-authorization-server/auth/v1`
OIDC discovery	`https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/.well-known/openid-configuration`
MCP PRM	`https://api.grainledger.com/.well-known/oauth-protected-resource`

MCP (AI agents)

Grain exposes a read-only MCP server at https://api.grainledger.com/mcp for ChatGPT and other MCP clients. MCP uses the same OAuth identity and organization permissions; org scoping is via organizationId in tool arguments instead of X-Organization-Id. See MCP. MCP is read-only because it exposes only read tools. OAuth tokens still identify the signed-in user, and Grain checks organization permissions on each tool call.

Authorization request example

https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/authorize
  ?response_type=code
  &client_id=YOUR_CLIENT_ID
  &redirect_uri=https://yourapp.com/oauth/callback
  &scope=openid%20email%20profile
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj

Generate code_challenge as the Base64URL-encoded SHA-256 hash of a random code_verifier string. Keep the verifier secret until the token exchange.

Token exchange

curl -X POST "https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=authorization_code" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://yourapp.com/oauth/callback" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "code_verifier=YOUR_CODE_VERIFIER"

const tokenResponse = await fetch("https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/token", {
  method: "POST",
  headers: { "Content-Type": "application/x-www-form-urlencoded" },
  body: new URLSearchParams({
    grant_type: "authorization_code",
    code,
    redirect_uri: redirectUri,
    client_id: clientId,
    code_verifier: codeVerifier,
  }),
});

X-Organization-Id header with OAuth

Every OAuth API request must include the organization (church) whose data you are accessing:

X-Organization-Id: cm123abc456def

Users can belong to multiple organizations. The OAuth flow does not scope to a single org; your application specifies the org per request. See Organizations for how to obtain the ID.

OAuth scopes

Standard OIDC scopes control user profile data in tokens:

Scope	Description
`openid`	OpenID Connect identity
`email`	Email address
`profile`	Name and profile information
`phone`	Phone number

API access is granted per user session. Permissions (for example view transactions, manage donors) are enforced based on the user’s role in the specified organization.

Example API request

curl -X GET "https://api.grainledger.com/api/v1/donors?page=1&limit=20" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "X-Organization-Id: cm123abc456def" \
  -H "Content-Type: application/json"

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

import requests

response = requests.get(
    "https://api.grainledger.com/api/v1/donors",
    params={"page": 1, "limit": 20},
    headers={
        "Authorization": f"Bearer {access_token}",
        "X-Organization-Id": organization_id,
    },
)

Token refresh

Use the refresh token from the token exchange to obtain new access tokens when they expire:

curl -X POST "https://pqnoojlycpbwbatbdgep.supabase.co/auth/v1/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=refresh_token" \
  -d "refresh_token=YOUR_REFRESH_TOKEN" \
  -d "client_id=YOUR_CLIENT_ID"

Refresh tokens before they expire to avoid interrupting active integrations.

Overview

Core concepts

Organization API keys

API key scopes

Rotation and revocation

OAuth 2.1 flow

OAuth endpoints

MCP (AI agents)

Authorization request example

Token exchange

X-Organization-Id header with OAuth

OAuth scopes

Example API request

Token refresh

​Organization API keys

​API key scopes

​Rotation and revocation

​OAuth 2.1 flow

​OAuth endpoints

​MCP (AI agents)

​Authorization request example

​Token exchange

​X-Organization-Id header with OAuth

​OAuth scopes

​Example API request

​Token refresh

Organization API keys

API key scopes

Rotation and revocation

OAuth 2.1 flow

OAuth endpoints

MCP (AI agents)

Authorization request example

Token exchange

X-Organization-Id header with OAuth

OAuth scopes

Example API request

Token refresh