Skip to main content

2. Get Credentials

2. Get Credentials

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.
Back to top