Integration Patterns

These patterns apply across the standard journey steps. Read this once before implementing individual flows.

Environment configuration

Keep base URLs in config and swap by environment:

ENDAOMENT_AUTH_URL=https://auth.dev.endaoment.org
ENDAOMENT_API_URL=https://api.dev.endaoment.org

Examples in this quickstart use dev. Do not hardcode production URLs while building.

Backend proxy

Endaoment user access tokens must stay on your server. Your frontend calls your backend; your backend calls Endaoment with the user’s Bearer token.

async function proxyToEndaoment(path, token, options = {}) {
  const response = await fetch(`${process.env.ENDAOMENT_API_URL}${path}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
      ...options.headers,
    },
  });

  return response.json();
}

Why: OAuth tokens are secrets. Never expose them in browser code or mobile clients.

OAuth with PKCE

Standard donor integrations authenticate users with OAuth 2.0 Authorization Code + PKCE:

Your backend creates code_verifier, code_challenge, and state.
Redirect the user to {AUTH_URL}/auth with client_id, redirect_uri, PKCE params, scopes, and prompt=consent when you need refresh tokens.
User logs in; Endaoment redirects back with code and state.
Your backend exchanges the code at POST {AUTH_URL}/token using Authorization: Basic base64(clientId:clientSecret) and the stored code_verifier.
Store access_token (and optionally refresh_token) for subsequent API calls.

Scopes: The auth server supports:

Scope	Claims / purpose
`openid`	OpenID Connect baseline
`accounts`	FDX account data
`transactions`	FDX transaction data
`profile`	`first_name`, `last_name`, `wallet`
`email`	User email address
`address`	User physical address
`offline_access`	Refresh tokens (requires `prompt=consent` on the authorize request)

Common quickstart combination: openid accounts transactions profile email address. Add offline_access only when you need refresh tokens — and include prompt=consent on the /auth redirect or refresh tokens are silently omitted. Redirect URIs: Local dev commonly uses http://localhost:5454. Register all redirect URLs with Endaoment before testing. Full PKCE implementation: GitHub quickstart sample.

Dev token shortcut

While OAuth is in progress, issue test tokens with the Access Token Issuer Tool. Development only—not for production.

Bearer authentication

Authenticated Endaoment API calls use the user’s access token:

Authorization: Bearer <access_token>

Verify the caller with GET /v1/auth/whoami.

Partner auth options

Most partner endpoints require x-api-key. Acting-user context varies by endpoint — check the specific API reference page before integrating. POST /v1/funds/partner accepts either a registered OAuth user Bearer token or partner server-to-server credentials (x-api-key, optionally with impersonation headers or body partnerUserIdentifier).

Partner fund creation (`POST /v1/funds/partner`)

Pick the path that matches your integration preference:

Path	Headers / body	Best for
A. Registered OAuth user bearer	`Authorization: Bearer <access_token>`	Standard OAuth quickstart after user login
B. API key + body user id	`x-api-key` + `partnerUserIdentifier` in body	Pure server-to-server; user already provisioned
C. API key + impersonation header	`x-api-key` + `x-endaoment-user-id`	Server-to-server when you store Endaoment user UUIDs
D. Partner OIDC bearer	`Authorization: Bearer <partner_oidc_token>`	Partner apps that already hold an OIDC access token

When both a header/OIDC user and body partnerUserIdentifier are supplied, they must resolve to the same user.

Partner settled donations (`POST /v1/donation-pledges/partner/*-settled`)

Path	Headers / body	Best for
A. API key + impersonation header	`x-api-key` + `x-endaoment-user-id`	Partners that track Endaoment user UUIDs
B. API key + body user id	`x-api-key` + `partnerUserIdentifier` in body	API-key-only when partner inflow routes are enabled and partner has `canManageUsers`

Other partner endpoints

Endpoint	Typical auth
`POST /v1/auth/partner/users`	`x-api-key` only
`GET /v1/funds/partner/{id}`	`x-api-key` only
`POST /v1/transfers/partner/grant-submissions`	`x-api-key` only
`POST /v1/missing-org-reports/tech-platform`	`x-api-key` only

See Partner Journey and Partner Endpoints.

Idempotency

Donation pledges and grant submissions require an idempotencyKey in the request body. Generate a new UUID per user action, and reuse that same key for every retry of that action.

An identical replay returns the original record instead of creating a second one. This is what makes retrying safe.
A changed payload under the same key is rejected, almost always as 409 Conflict. Either way your change is not applied and the original record is untouched. The rejection is what you can rely on, not the exact status.
A settled pledge cannot be amended by replaying it. Settled routes record money that has already moved, so a corrected amount sent under the same key is rejected rather than applied. Reaching for a new key does not get the correction in either: keep the same partnerOperationId and you get another 409, because that is the pair we record against. Change the partnerOperationId as well and it does go through, as a second and separate donation for money that moved once. Ask us to correct the record instead.

Which conflicts are worth retrying, and what to do with the rest: Conflicts on write routes.

import { randomUUID } from 'crypto';

const idempotencyKey = randomUUID();

Amounts in microdollars

Monetary fields use microdollars (1 USD = 1_000_000):

Dollars	Microdollars
$1.00	`1000000`
$100.00	`100000000`

const microdollars = Math.round(dollars * 1_000_000);

Public vs authenticated endpoints

Some endpoints do not require a Bearer token:

Endpoint	Auth
`GET /v2/orgs/search`	None
`GET /v1/donation-pledges/wire/details/domestic`	None
`GET /v1/donation-pledges/wire/details/international`	None

You may call these from your backend or directly from a client. Authenticated flows should still prefer a backend proxy for consistency.

Optional: collaborators

To add or remove fund collaborators after opening a fund, see Manage Collaborators in the Collaboration endpoint bucket.

About

Quickstart

Endpoints

Smart Contracts

Integration Patterns

Environment configuration

Backend proxy

OAuth with PKCE

Dev token shortcut

Bearer authentication

Partner auth options

Partner fund creation (`POST /v1/funds/partner`)

Partner settled donations (`POST /v1/donation-pledges/partner/*-settled`)

Other partner endpoints

Idempotency

Amounts in microdollars

Public vs authenticated endpoints

Optional: collaborators

​Environment configuration

​Backend proxy

​OAuth with PKCE

​Dev token shortcut

​Bearer authentication

​Partner auth options

​Partner fund creation (POST /v1/funds/partner)

​Partner settled donations (POST /v1/donation-pledges/partner/*-settled)

​Other partner endpoints

​Idempotency

​Amounts in microdollars

​Public vs authenticated endpoints

​Optional: collaborators

Environment configuration

Backend proxy

OAuth with PKCE

Dev token shortcut

Bearer authentication

Partner auth options

Partner fund creation (`POST /v1/funds/partner`)

Partner settled donations (`POST /v1/donation-pledges/partner/*-settled`)

Other partner endpoints

Idempotency

Amounts in microdollars

Public vs authenticated endpoints

Optional: collaborators