Skip to main content

​
Prerequisites

  • An mgPass partner account with an API key (provided by MG Digital)
  • Your platform’s user IDs mapped to mgPass user IDs

​
Step 1: Get Your API Key

Your API key is issued when you’re onboarded as a partner. It looks like this: 
pk_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
Store your API key securely. It cannot be retrieved after initial issuance. If lost, contact MG Digital to rotate it.

​
Step 2: Publish Your First Event

curl -X POST https://pass.mgdm.dev/api/partner/events \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "user_id": "usr_abc123",
    "event_type": "article_read",
    "metadata": {
      "reference_id": "article_456"
    }
  }'
Response: 
{
  "accepted": true,
  "points_awarded": 10,
  "event_id": "evt_xyz789"
}
That’s it — the user just earned 10 points.

​
Step 3: Check the User’s Balance

Users can check their balance through your app using their OAuth token: 
curl https://pass.mgdm.dev/api/account/rewards \
  -H "Authorization: Bearer USER_ACCESS_TOKEN"

{
  "total_points": 1510,
  "lifetime_earned": 5010,
  "tier": "silver",
  "tier_details": {
    "name": "silver",
    "min_points": 1000,
    "multiplier": 1.5
  }
}

​
What Happens Behind the Scenes

When you publish an event:
  1. Rule matching — The engine finds the best rule for this event_type + user’s tier
  2. Point calculation — Base points from the rule, multiplied by the tier multiplier
  3. Cap enforcement — Daily and monthly caps are checked and enforced
  4. Atomic credit — Points are added to the ledger and balance in a single transaction
  5. Tier promotion — If lifetime points cross a threshold, the user is promoted

​
Next Steps