Skip to main content

2. Onboarding & Partnership

Onboarding & Partnership

To use the Partner API you must be an approved partner. The Partner API is not self-serve — there is no public sign-up endpoint. Access is granted by SIR Giving administrators after a partnership review.

Why approval is required

Two reasons:

  1. Token pool funding. Every reward you issue draws from a token pool that SIR Giving allocates to you. We need to size the pool to your expected volume and lock in restrictions (vesting, expiration, redemption rules) before you start issuing.
  2. Compliance and trust. SIR tokens are redeemable for real value. Every approved partner is contractually bound to acceptable-use terms and provides KYB/identity verification.

Approval workflow

Partner Inquiry
     │
     ▼
Sales / Business Review ──── (reject)
     │ approved
     ▼
Contract & Compliance signed
     │
     ▼
Admin creates Partner record (status: PENDING_APPROVAL)
     │
     ▼
Admin generates API key pair  (POST /api/v1/admin/partners/:id/keys)
     │
     ▼
Admin allocates initial token pool
     │
     ▼
Partner status set to ACTIVE  ─── you can now call the API
     │
     ▼
Sandbox testing → Production cutover

What we need from you to start

Item Purpose
Partner name & legal entity Account record
Contact email Operational notifications, key expiry alerts
Use case summary Sizing token pool, identifying required stakeholder types
Integration model Server-to-server only / widget-only / both
Expected monthly action volume Rate limit tier (Standard / Professional / Enterprise)
Action types you'll submit We register stakeholderTypeCode values you'll use
Webhook endpoint URL (optional at start) We'll register this for you
IP allowlist (optional) Restricts where keys are valid

What we provide back

  • Partner ID — Mongo ObjectId, used in admin URLs.
  • Partner slug — short string used in some responses.
  • One API key pair:
    • Publishable key: pk_test_<64hex> (sandbox) or pk_live_<64hex> (prod)
    • Secret key: sk_test_<64hex> or sk_live_<64hex>
    • HMAC signing secret: 64-char hex string
  • Token pool with allocated balance you can draw from.
  • Default campaign (optional) defining split rules for your common action types.

The secret key and HMAC secret are returned once, in the response body when the key is generated. They are never retrievable again. If lost, an admin must rotate the key — your old key will continue to work until revoked, allowing zero-downtime rotation.

API key types — pk vs sk

Property Publishable (pk_) Secret (sk_)
Where it lives Browser, mobile app, HTML Server only
Auth headers needed X-Partner-Key only X-Partner-Key + X-Timestamp + X-Signature
What it can do Read public partner config, look up nonprofit by slug, create donation links All of the above + submit actions, manage users/webhooks/campaigns, view transactions
If leaked Low blast radius (rate-limited, scoped) High — rotate immediately

The @RequiresSecretKey() decorator marks endpoints (e.g. action submission, webhook registration, action reversal) that reject pk_ keys with 403 Forbidden.

Environments

live keys talk to api.sirgiving.org. test keys talk to devapi.sirgiving.org. The HMAC guard does not enforce environment matching at the network layer — the key prefix tells us which dataset to operate against. Always test against the sandbox first.

Partner tiers and rate limits

Your tier is set by an admin based on contract terms:

Tier Hourly Burst (per minute)
Standard 1,000 100
Professional 5,000 500
Enterprise 20,000 2,000

Headers on every response:

  • X-RateLimit-Limit — your hourly cap
  • X-RateLimit-Remaining — requests left in window
  • X-RateLimit-Reset — unix timestamp when window resets
  • X-RateLimit-RetryAfter (only on 429) — seconds to wait

Partner statuses

  • PENDING_APPROVAL — record created but cannot call API.
  • ACTIVE — full access.
  • SUSPENDED — all calls return 401 PARTNER_SUSPENDED. Reach out to support.
  • Other non-ACTIVE states return 401 PARTNER_NOT_ACTIVE.

The partner.status_changed webhook fires whenever your status transitions.

Key rotation & revocation

Admins can:

  • Rotate: POST /api/v1/admin/partners/:id/keys/:keyId/rotate issues a brand-new pair with the same scopes; the old pair stays active until you explicitly revoke it.
  • Revoke: DELETE /api/v1/admin/partners/:id/keys/:keyId deactivates immediately.

The api_key.expiring webhook fires before a key reaches its expiresAt.

Back to top