BigMindBigMindBigMind
Partner API
Sign inGet an API key
Partner API
OverviewAuthenticationCustomersPlansQuotesAccount & UsageBackup statusWebhooksError codesChangelog

Authentication

The Partner API uses bearer-token authentication with API keys you generate from the Settings page.

Generate a key

Go to Settings → API and click Generate API key. Give it a name (e.g., Production or Billing integration).

The full secret is shown once. Copy it and store it somewhere safe — a password manager or your secret store. If you lose the secret, regenerate the key (the old one is immediately revoked).

One active key per partner. Multiple keys with scoped permissions are on the roadmap.

Authenticate requests

Include the secret on every request via the Authorization header:

curl -H "Authorization: Bearer sk_live_..." \
  https://eu-bigmind2.genie9.com/api/partner/v1/account

For compatibility, the X-API-Key header is also accepted.

Response envelope

All responses use the same JSON envelope:

{
  "success": true,
  "data": { ... }
}

See the full list of error codes on the Errors reference.

Rate limits

The API is rate-limited to 120 requests per minute per partner, per API server. When exceeded you receive HTTP 429 with a Retry-After header indicating seconds until you can retry.

Idempotent requests

A retry after a lost response must not create or charge twice. Send an Idempotency-Key header (1–255 characters, unique per intent — a UUID) on any write; the API stores the response for 24 hours and answers a retry with the same key and the same body from the store, with Idempotent-Replayed: true. Keys are scoped to your partner account.

  • First request with a key: runs normally; the response carries Idempotent-Replayed: false.
  • Same key, same body, within 24 hours: the stored response — same status, same body (the same customer.id) — with Idempotent-Replayed: true. Nothing runs again.
  • Same key, different body: 422 IDEMPOTENCY_KEY_REUSED. A new request takes a new key.
  • Same key while the first request is still running: 409 IDEMPOTENCY_IN_PROGRESS with Retry-After: 2; retry and you get the stored response.
  • A 5xx is not stored: the retry runs the request again. 4xx refusals are stored and replayed like any response.

Honoured on POST /v1/customers, PATCH and DELETE /v1/customers/{id}, suspend, reactivate, DELETE …/pending-change, the plan-change preview, POST /v1/quotes, the tag writes and the webhook writes (not on send-welcome or quotes/compare, which are safe to repeat). A request without the header behaves as before; a GET ignores it. Keys are case-sensitive. A 429 is never stored: retry it with the same key.

import { randomUUID } from 'crypto';

// One key per intent: keep it with the order / ticket so a retry reuses it.
const key = order.idempotencyKey ??= randomUUID();

const res = await fetch('https://eu-bigmind2.genie9.com/api/partner/v1/customers', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_live_...',
    'Content-Type': 'application/json',
    'Idempotency-Key': key,
  },
  body: JSON.stringify({ email: 'ann@example.com', planId: 'bigmind-standard-monthly', seats: 3 }),
});
console.log(res.status, res.headers.get('Idempotent-Replayed')); // 201 false — or 201 true on a retry

Key rotation

To rotate a key, go to Settings → API and click Regenerate. The old key is revoked immediately and the new secret is shown once. Update your integrations before regenerating.

To revoke without replacement, click Revoke. All subsequent requests with the revoked secret return HTTP 401 with INVALID_API_KEY.

Account state

The key follows your partner account. A suspended account's key answers 401 INVALID_API_KEY. An expired account is read-only: GET requests work, every write answers 403 PARTNER_READ_ONLY. While your account is being migrated from BigMIND 1.0, writes answer 423 MIGRATION_IN_PROGRESS and reads keep working.