Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.grainledger.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Overview

The Grain API uses OAuth 2.1 (Sign in with Grain) for authentication. Users authorize your application to access their church data, and you receive an access token to make API calls on their behalf.

​
OAuth 2.1 Flow

  1. Redirect to authorize – Redirect the user to the Grain authorization endpoint with your client ID, redirect URI, scopes, and PKCE parameters.
  2. User consents – The user signs in (if needed) and approves access at https://app.grainledger.com/oauth/consent.
  3. Receive authorization code – The user is redirected back to your redirect_uri with an authorization code.
  4. Exchange for tokens – Exchange the code for access and refresh tokens at the Grain token endpoint.
  5. Call the API – Include the access token in the Authorization: Bearer <token> header and X-Organization-Id in every request.

​
OAuth Endpoints

PurposeURL
Authorizationhttps://app.grainledger.com/oauth/authorize
Tokenhttps://api.grainledger.com/oauth/token
Consent UIhttps://app.grainledger.com/oauth/consent
Discoveryhttps://api.grainledger.com/.well-known/oauth-authorization-server

​
X-Organization-Id Header

Every API request must include the organization (church) whose data you are accessing: 
X-Organization-Id: org_abc123xyz
Users can belong to multiple organizations. The organization ID is available from the Grain app when the user selects an organization. Your OAuth flow does not scope to a single org; the caller specifies the org per request.

​
Scopes

Standard OIDC scopes control user profile data in tokens:
ScopeDescription
openidOpenID Connect identity
emailEmail address
profileName and profile information
phonePhone number
API access is granted per user session. Permissions (e.g. view transactions, manage donors) are enforced based on the user’s role in the specified organization.

​
Example Request

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

​
Token Refresh

Use the refresh token from the token exchange to obtain new access tokens when they expire. Call the token endpoint with grant_type=refresh_token and your refresh token.