2. Get Credentials

Onboarding2. &Get PartnershipCredentials

Get Credentials

ToThis usepage theexplains Partnerhow you get access, what credentials mean, and what still has to be approved before rewards can be issued.

Sandbox vs production

Environment Purpose What you can do Sandbox Build and test your integration Create keys, make signed API youcalls, musttest bedonation anlinks, approvedtest partner.reward Theflows Partnerif APIa sandbox token pool is notprovisioned self-serve —thereProduction isIssue noreal publicrewards sign-upRequires endpoint.approval, Accessproduction iscredentials, grantedand bya production token pool

Self-service credentials

If you have a SIR Giving administratorsaccount afterwith access to partner keys, creating your first API key automatically creates a partnershipPartner review.record linked to your user.

Use:

POST /v1/partner/keys
Authorization: Bearer <your user JWT>
Content-Type: application/json

{
  "name": "Sandbox Integration",
  "environment": "sandbox",
  "keyType": "secret"
}

The response includes:

{
  "id": "key_...",
  "partnerId": "...",
  "name": "Sandbox Integration",
  "environment": "sandbox",
  "publicKey": "pk_test_...",
  "secretKey": "sk_test_...",
  "hmacSecret": "64-character-hex-string"
}

Store secretKey and hmacSecret immediately. They are not shown again.

WhyProduction approval

Production rewards require approval isbecause requiredSIR

Twotokens reasons:

have

real Tokenvalue pooland funding. Everyevery reward you issue draws from a token poolpool. that

Before production launch, 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.

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

needs:

Item	PurposeWhy it matters
Partner name &and legal entity	Account and compliance record
Contact email	Operational notifications,alerts and key expiry alertsnotices
Use case summary	SizingConfirms acceptable use and token pool, identifying required stakeholder types

Integration model Server-to-server only / widget-only / botheconomics Expected monthly action volume RateSets limitrate tierlimits (Standardand /token Professionalpool / Enterprise)size Action types you'llConfirms what events you will submit WeStakeholder registermodel stakeholderTypeCodeConfirms valueswho you'llreceives userewards Webhook endpoint URL (optional at start) We'llLets registerSIR thisGiving forsend youreward lifecycle IP allowlist (optional) Restricts where keys are validevents

What

After weapproval, provideSIR backGiving provides or enables:

• PartnerProduction IDAPI — Mongo ObjectId, used in admin URLs.credentials.
• PartnerA slugproduction —token short string used in some responses.pool.
• One API key pair:
• Publishable key: pk_test_<64hex> (sandbox)Campaign or pk_live_<64hex>reward (prod)rules, if needed.
• SecretProduction key:webhook sk_test_<64hex> or sk_live_<64hex>

HMAC signing secret: 64-char hex stringconfiguration.

What

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 theeach 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 skfor

PropertyKey	PublishableWhere (pk_)it belongs	SecretUse (sk_)it for
Wherepk_test_... itor livespk_live_...	Browser,Browser or mobile app, HTMLapp	ServerDonation onlylinks, public config, organization lookup
Authsk_test_... headersor neededsk_live_...	X-Partner-KeyBackend only	X-Partner-KeyUsers, +actions, X-Timestampcampaigns, +token X-Signaturepools, webhooks, dashboard data
What it can dohmacSecret	ReadBackend publicsecret partner config, look up nonprofit by slug, create donation linksmanager	AllSigning ofserver-to-server the above + submit actions, manage users/webhooks/campaigns, view transactions

If leaked Low blast radius (rate-limited, scoped) High — rotate immediatelyrequests

Check your partner record

TheAfter creating a key, verify your Partner record:

@RequiresSecretKey()GET /v1/partner/keys/partner-info
Authorization: Bearer <your user JWT>

decorator

You marksshould endpointssee (e.g.your actionpartner submission,ID, webhookname, registration,slug, actionstatus, reversal)enabled thatfeatures, rejectand rate limit.

Check your keys

pk_GET /v1/partner/keys
Authorization: Bearer <your user JWT>

This lists keys with 403 Forbidden.

Environments

live keys talk to api.sirgiving.org. test keys talk to devapi.sirgiving.org. The HMAC guardbut does not enforcereturn environmentsecret matchingvalues.

at

Go-live checklist

Before switching to production:

You have a pk_live_... and sk_live_... key. Your backend signs requests with the networkproduction layerhmacSecret. —You have an active production token pool. Your webhook endpoint is reachable from the keypublic prefixinternet. tellsYour uswebhook whichhandler datasetverifies toX-SIR-Signature. operateYour against.action Alwaysrequests testuse againststable, theunique sandboxidempotencyKey first.values.

Partner

You tiershave tested retries and rate limitslimit

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 waithandling.

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.