# 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:

1. A partner account.
2. An API key pair for the environment you are using.
3. 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](./3-authentication-hmac-signing) |
| I want to add a donation button | [End-to-End Scenarios: Donation widget](./6-end-to-end-scenarios#scenario-1-add-a-donation-button) |
| I want to reward a user for an action | [End-to-End Scenarios: Reward a user](./6-end-to-end-scenarios#scenario-2-reward-a-user-for-an-action) |
| I want to receive events | [Webhooks](./5-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

1. Create or receive sandbox credentials.
2. Store the `sk_...` key and HMAC secret in your backend environment.
3. Make a signed `GET /v1/partner/users` request.
4. If you are building a widget, create a donation link with the `pk_...` key.
5. If you are issuing rewards, confirm you have an active sandbox token pool.
6. Submit a test action with a unique `idempotencyKey`.
7. Register a webhook and send a test event.
8. 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`.