Skip to content
MapleGatherMapleGather Help

Getting started with the MapleGather API

By the end of this guide, you’ll have a scoped API key for authenticating requests, a working knowledge of the API’s wire contract, and a registered webhook endpoint that receives signed events. It takes about 15 minutes.

What you’ll need

Section titled “What you’ll need”
  • An admin account with api_keys:write and webhooks:write scopes.
  • A publicly reachable HTTPS server to receive webhook deliveries (optional for the key step; required for the webhook step).
  • Familiarity with HTTP requests and HMAC-SHA256.

Step 1 — Issue your first API key

Section titled “Step 1 — Issue your first API key”

API keys authenticate your requests to the MapleGather REST API. Each key carries only the scopes you explicitly grant, following the principle of least privilege.

  1. Go to Admin & Security > Integrations > API keys.
  2. Select New API key.
  3. Enter a descriptive Name (for example, “Integration test key”).
  4. In the Scopes section, select the scopes your integration needs. For a read-only exploratory key, select members:read and payments:read.
  5. Leave the Expiry set to one year (or clear it to set “Never”).
  6. Select Create API key.

The full token is shown exactly once in the format mg_live_<32 base32 characters>. Copy it now and store it securely (your secrets manager, .env file, or similar). Select I’ve stored it safely to close the reveal. The token cannot be retrieved again — you can only rotate the key to get a new one.

You should now see the key in the API keys list with status “Active” and only the first eight characters of the token displayed.

Step 2 — Explore the interactive API docs

Section titled “Step 2 — Explore the interactive API docs”

The interactive docs let you browse every endpoint, try authenticated requests, and download the OpenAPI 3.1 spec for SDK codegen.

  1. From the API keys page, select API docs ↗ (top-right of the page header), or go to Admin & Security > Integrations and select the Interactive docs card.
  2. The docs open in a new tab, served from GET /bc/v1/openapi.json.

Cross-cutting behaviors to understand before writing integration code:

  • Idempotency (Idempotency-Key header): Include a unique Idempotency-Key (UUID or similar) on every POST and PATCH request. The server caches the first response for 24 hours — resending the same key returns the cached result rather than re-executing the operation. A repeated key with a different request body returns 409.
  • Rate limits: Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. If you exceed the limit, the response is 429 with a Retry-After header. The burst tolerance is ≤200 requests over 10 seconds — implement exponential backoff for retries.
  • Cursor pagination: List endpoints return a nextCursor in the response envelope. Pass it as the cursor query parameter in the next request. Maximum limit is 100 per page. If a cursor becomes invalid, restart from the first page (omit cursor).
  • Batch: Send up to 100 operations in a single request with POST /bc/v1/orgs/{orgId}/batch. The response is a per-operation result array. Batch execution is non-atomic — one failure does not roll back other operations.
  • Errors: All 4xx and 5xx responses are application/problem+json. The Problem schema covers most errors; ValidationProblem adds a violations array for field-level validation failures.

Step 3 — Register a webhook endpoint

Section titled “Step 3 — Register a webhook endpoint”

Webhooks push events to your server the moment they occur — no polling required.

  1. Go to Admin & Security > Integrations > Webhooks.
  2. Select New endpoint.
  3. Enter your HTTPS delivery URL. HTTP is not accepted.
  4. Select the event types you want to receive. The M1 catalog: member.created, payment.succeeded, event_registration.confirmed.
  5. Leave API version at v1.
  6. Select Create endpoint.

The HMAC signing secret is shown once. Copy it now. After you dismiss, add this secret to your receiver.

Verifying signatures in your receiver:

Every delivery includes two headers:

  • X-Webhook-Signature — an HMAC-SHA256 hex digest.
  • X-Webhook-Timestamp — a Unix timestamp (seconds).

To verify:

  1. Construct the signed string: <X-Webhook-Timestamp>.<raw request body>.
  2. Compute HMAC-SHA256 of that string using your signing secret.
  3. Compare your result to X-Webhook-Signature (use a constant-time comparison to prevent timing attacks).
  4. Reject the delivery if X-Webhook-Timestamp is more than five minutes in the past (replay defense).

If this matches, the delivery is authentic. Return 2xx to acknowledge; MapleGather retries non-2xx responses up to six times over approximately 24 hours.

  1. Optionally, select Send a test event to verify your receiver is working. The test fires a signed ping delivery and shows the result (“Delivered ✓” or “Failed — {status}”).

You should now see your endpoint in the Webhooks list with status “Active” and the event types you selected.

What you’ve set up

Section titled “What you’ve set up”

You now have:

  • A scoped API key for authenticating API requests.
  • A working knowledge of idempotency, rate limits, pagination, batch, and error shapes.
  • A webhook endpoint receiving signed events, with signature verification in place.

Next, you might want to: