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

```http
POST /v1/partner/keys
Authorization: Bearer <your user JWT>
Content-Type: application/json

{
  "name": "Sandbox Integration",
  "environment": "sandbox",
  "keyType": "secret"
}
```

The response includes:

```json
{
  "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:

```http
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

```http
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.