2. Get Credentials

This page explains how 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 calls, test donation links, test reward flows if a sandbox token pool is provisioned 
 
 
 Production 
 Issue real rewards 
 Requires approval, production credentials, and a production token pool 
 
 
 
 Self-service credentials 
 If you have a SIR Giving account with access to partner keys, creating your first API key automatically creates a Partner 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. 
 Production approval 
 Production rewards require approval because SIR tokens have real value and every reward draws from a token pool. 
 Before production launch, SIR Giving needs: 
 
 
 
 Item 
 Why it matters 
 
 
 
 
 Partner name and legal entity 
 Account and compliance record 
 
 
 Contact email 
 Operational alerts and key expiry notices 
 
 
 Use case summary 
 Confirms acceptable use and token economics 
 
 
 Expected monthly action volume 
 Sets rate limits and token pool size 
 
 
 Action types 
 Confirms what events you will submit 
 
 
 Stakeholder model 
 Confirms who receives rewards 
 
 
 Webhook URL 
 Lets SIR Giving send reward lifecycle events 
 
 
 
 After approval, SIR Giving provides or enables: 
 
 Production API credentials. 
 A production token pool. 
 Campaign or reward rules, if needed. 
 Production webhook configuration. 
 
 What each key is for 
 
 
 
 Key 
 Where it belongs 
 Use it for 
 
 
 
 
 pk_test_... or pk_live_... 
 Browser or mobile app 
 Donation links, public config, organization lookup 
 
 
 sk_test_... or sk_live_... 
 Backend only 
 Users, actions, campaigns, token pools, webhooks, dashboard data 
 
 
 hmacSecret 
 Backend secret manager 
 Signing server-to-server requests 
 
 
 
 Check your partner record 
 After creating a key, verify your Partner record: 
 GET /v1/partner/keys/partner-info
Authorization: Bearer <your user JWT>
 
 You should see your partner ID, name, slug, status, enabled features, and rate limit. 
 Check your keys 
 GET /v1/partner/keys
Authorization: Bearer <your user JWT>
 
 This lists keys but does not return secret values. 
 Go-live checklist 
 Before switching to production: 
 
 You have a pk_live_... and sk_live_... key. 
 Your backend signs requests with the production hmacSecret . 
 You have an active production token pool. 
 Your webhook endpoint is reachable from the public internet. 
 Your webhook handler verifies X-SIR-Signature . 
 Your action requests use stable, unique idempotencyKey values. 
 You have tested retries and rate limit handling.