1. Start Here
1. Start Here
SIR Giving Partner API
Use the SIR Giving Partner API to add SIR rewards to your product. You can create donation links, reward users for actions in your own system, track balances, and receive webhook events when rewards are issued or reversed.
Most teams use one of two paths:
| If you want to... | Start with |
|---|---|
| Add a donation button or embedded donation flow | A publishable key (pk_...) and the donation endpoints |
| Reward users for purchases, volunteering, referrals, or other actions | A secret key (sk_...), HMAC signing, and the actions endpoints |
| Listen for reward status changes | Webhooks |
| Test before launch | Sandbox credentials and a sandbox token pool |
What you need before you call the API
You need three things:
- A partner account.
- An API key pair for the environment you are using.
- A funded token pool if you want to distribute SIR tokens.
Creating credentials lets you authenticate. It does not automatically mean you can issue real rewards. Rewards draw from a token pool, and production token pools require SIR Giving approval.
Base URLs
| Environment | Base URL | Key prefix |
|---|---|---|
| Sandbox | https://devapi.sirgiving.org |
pk_test_..., sk_test_... |
| Production | https://api.sirgiving.org |
pk_live_..., sk_live_... |
All partner integration endpoints are under /v1/partner/.
Interactive API docs are available at /partner-api on each host.
Choose your first tutorial
| Goal | Use this |
|---|---|
| I want to make my first signed backend request | Authentication & HMAC Signing |
| I want to add a donation button | End-to-End Scenarios: Donation widget |
| I want to reward a user for an action | End-to-End Scenarios: Reward a user |
| I want to receive events | Webhooks |
Key concepts
Partner
Your organization or developer account in SIR Giving. API keys, token pools, campaigns, users, and webhooks all belong to a partner.
API key pair
Each key issuance returns:
- A publishable key, such as
pk_test_..., safe for browser use. - A secret key, such as
sk_test_..., for backend use only. - An HMAC signing secret, used to sign server-to-server requests.
The secret key and HMAC secret are shown once. Store them in a secret manager.
Token pool
A funded bucket of SIR tokens allocated to your partner. Reward actions debit this pool. If there is no active pool in the same environment as your API key, action submission can authenticate but still fail during processing.
Action
The unit of reward work you send to SIR Giving. For example: a purchase, volunteer shift, donation, referral, or advocacy event. Actions include an idempotencyKey so retries do not duplicate rewards.
Partner user
A user from your system mirrored into SIR Giving using your stable externalUserId. Partner users receive balances when actions reward them.
Webhook
An outbound event sent from SIR Giving to your server when important things happen, such as action.completed or token_pool.low_balance.
The shortest path to a working integration
- Create or receive sandbox credentials.
- Store the
sk_...key and HMAC secret in your backend environment. - Make a signed
GET /v1/partner/usersrequest. - If you are building a widget, create a donation link with the
pk_...key. - If you are issuing rewards, confirm you have an active sandbox token pool.
- Submit a test action with a unique
idempotencyKey. - Register a webhook and send a test event.
- Repeat the same flow in production after your production token pool is approved.
Common confusion
My key works, but actions fail. Why?
Authentication only proves your key is valid. Reward actions also need an active token pool in the same environment.
Can I use a publishable key for server actions?
No. Mutation endpoints such as action submission and webhook registration require a secret key.
Can I use sandbox keys against production?
Do not do this. Use test keys with devapi.sirgiving.org and live keys with api.sirgiving.org.