1. Start Here

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/users request. 
 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 .