# 4. API Reference

All paths are relative to:

- Sandbox: `https://devapi.sirgiving.org`
- Production: `https://api.sirgiving.org`

## Auth legend

| Label | Meaning |
|---|---|
| JWT | User login token from the SIR Giving app |
| Widget | `X-Partner-Key: pk_...` only |
| HMAC | `X-Partner-Key`, `X-Timestamp`, and `X-Signature` |
| HMAC, secret key | HMAC request with `sk_...`; publishable keys are rejected |

## Partner key management

These endpoints are for signed-in users managing their own partner credentials.

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/partner/keys` | JWT | Create an API key pair |
| GET | `/v1/partner/keys` | JWT | List your API keys |
| GET | `/v1/partner/keys/partner-info` | JWT | Get your Partner record |
| GET | `/v1/partner/keys/:id` | JWT | Get one key record |
| PATCH | `/v1/partner/keys/:id` | JWT | Rename, deactivate, or set expiry |
| DELETE | `/v1/partner/keys/:id` | JWT | Delete/revoke a key |

## Partner auth

These endpoints support the partner portal.

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/partner/auth/login` | Email/password | Login to partner portal |
| GET | `/v1/partner/auth/me` | JWT | Get current partner user and publishable key |

## Widget/config endpoints

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/config` | Widget | Get partner widget config |
| GET | `/v1/partner/organizations/:slug` | Widget | Look up nonprofit details |
| POST | `/v1/partner/donations/create-link` | Widget | Create a donation checkout link |
| GET | `/v1/partner/donations/status/:partnerDonationId` | Widget | Check donation reward status |

## Users

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/users` | HMAC | List partner users |
| POST | `/v1/partner/users` | HMAC, secret key | Create a partner user |
| GET | `/v1/partner/users/:externalId` | HMAC | Get a user by your external ID |
| PATCH | `/v1/partner/users/:externalId` | HMAC, secret key | Update user metadata |
| GET | `/v1/partner/users/:externalId/balance` | HMAC | Get user balance |
| GET | `/v1/partner/users/:externalId/transactions` | HMAC | Get user action history |

## Actions

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/partner/actions/submit` | HMAC, secret key | Submit one reward action |
| GET | `/v1/partner/actions` | HMAC | List actions |
| GET | `/v1/partner/actions/:id` | HMAC | Get action status/details |
| POST | `/v1/partner/actions/:actionId/reverse` | HMAC, secret key | Reverse a completed action |
| POST | `/v1/partner/actions/bulk` | HMAC, secret key | Submit up to 100 actions synchronously |

`GET /v1/partner/actions/bulk/:jobId` is deprecated. Bulk actions are processed synchronously and return their result from `POST /bulk`.

## Token pools

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/token-pools` | HMAC | List allocated token pools |
| GET | `/v1/partner/token-pools/:id/balance` | HMAC | Get pool balance |
| POST | `/v1/partner/token-pools/request` | HMAC, secret key | Request more allocation |
| GET | `/v1/partner/token-pools/requests` | HMAC | List allocation requests |

## Campaigns

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/campaigns` | HMAC | List campaigns |
| GET | `/v1/partner/campaigns/active` | HMAC | Get active campaign |
| GET | `/v1/partner/campaigns/:id` | HMAC | Get campaign details |
| GET | `/v1/partner/campaigns/:id/analytics` | HMAC | Get campaign analytics |
| POST | `/v1/partner/campaigns` | HMAC, secret key | Create campaign |
| PATCH | `/v1/partner/campaigns/:id` | HMAC, secret key | Update campaign |

## Transactions

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/transactions` | HMAC | List partner transactions |
| GET | `/v1/partner/transactions/:id` | HMAC | Get transaction details |

## Dashboard

| Method | Path | Auth | Purpose |
|---|---|---|---|
| GET | `/v1/partner/dashboard/summary` | HMAC | Pool, activity, and user summary |
| GET | `/v1/partner/dashboard/trends` | HMAC | Daily activity trends |
| GET | `/v1/partner/dashboard/top-earners` | HMAC | Top rewarded users |
| GET | `/v1/partner/dashboard/webhooks/health` | HMAC | Webhook health |
| GET | `/v1/partner/dashboard/api-usage` | HMAC | API usage metrics |
| GET | `/v1/partner/dashboard/recent-activity` | HMAC | Recent actions |
| GET | `/v1/partner/dashboard/integration-health` | HMAC | Integration health |
| GET | `/v1/partner/dashboard/campaigns/:id/analytics` | HMAC | Campaign performance |

## Webhooks

| Method | Path | Auth | Purpose |
|---|---|---|---|
| POST | `/v1/partner/webhooks` | HMAC, secret key | Register webhook |
| GET | `/v1/partner/webhooks` | HMAC | List webhooks |
| DELETE | `/v1/partner/webhooks/:id` | HMAC, secret key | Delete webhook |
| GET | `/v1/partner/webhooks/:id/deliveries` | HMAC | List deliveries |
| POST | `/v1/partner/webhooks/:id/deliveries/:deliveryId/retry` | HMAC, secret key | Retry delivery |
| POST | `/v1/partner/webhooks/:id/test` | HMAC, secret key | Send test webhook |