Build on the identity rail.

Sign-in providers

A community chooses which it offers; the login page renders each by its real state — never a dead button. Provider policy is enforced at the route, not just the UI.

OIDC endpoints

Authorization-code + PKCE (S256) only. Public clients. Served on each community's issuer host.

DogTag & tags

Berify-verified NFC DogTags. Every tap is verified server-side; every binding carries an epoch, so a lost tag dies in seconds while the identity survives. Tap verification fails closed.

# All: Authorization: Bearer <tenant API key> · Content-Type: application/json
# Member fields (user_id / new_user_id) take a pgm_ member ref (what the
# graph API serves) — raw account uuids are accepted as a legacy courtesy only.

POST /api/tags/bind      { "tag_ref": "…", "user_id": "pgm_…" }
# 200 { "ok": true, "epoch": 1, "binding_id": "…" }

POST /api/tags/revoke    { "tag_ref": "…", "reason": "lost" }
# reason: lost | stolen | left | repointed | scheduled_rotation
# 200 { "ok": true, "revoked_epoch": 1 }

POST /api/tags/reissue   { "tag_ref": "…" }
# 200 { "ok": true, "old_epoch": 1, "new_epoch": 2 }

POST /api/tags/repoint   { "tag_ref": "…", "new_user_id": "pgm_…",
                           "to_tenant_slug": "other-community",   # optional
                           "consent_token": "…" }                 # cross-tenant only
# 200 { "ok": true, "old_epoch": 1, "new_epoch": 2 }
# 403 { "error": "consent_required" }   cross-tenant without a consent token
# (a cross-tenant new_user_id ref is the TARGET community's ref — ask them for it)

POST /api/tags/repoint-consent          # authenticated as the RECEIVING community
                         { "tag_ref": "…", "new_user_id": "pgm_…" }
# 200 { "ok": true, "consent_token": "…", "expires_in": 600 }

# Errors, all routes: 400 invalid_request (missing/malformed field) ·
# 400 invalid_json · 401 invalid_api_key · 404 not_found (tag/tenant/user —
# cross-tenant lookups answer not_found, no existence leak) · 409 conflict
# (already_bound / not_bound / …) · 503 berify_unavailable

The social graph — the community owns it

Connections form when members tap each other's DogTags, a member who goes private disappears from the graph, and Pernox sees only aggregate counts — never who is connected to whom.

Member refs are per-community. Every member-identifying value on this API is a pairwise ref (pgm_…) — the same member has a different ref in every community, and raw account ids never appear. Two communities cannot correlate members or intersect edges by comparing API responses. Refs are stable within a community, work as inputs everywhere a member is named (including the tags API), and resolve only under your own tenant key. Handles remain the one opt-in cross-site name.

The member's own floor lives on their account page, no API needed: their connections (a private peer collapses to a count, never a name), the visibility knob, and their declared interests — declared-only, never inferred, and gateable via the hasInterest leaf (topic ids are listed on your console's Gates page).

Wire shape: every response is wrapped { ok: true, <key>: … } (the key named per row below) and all fields are snake_case.

A missing or malformed parameter is 400 invalid_request; unknown refs answer with the same empty shapes as private members (no probe oracle). Connection suggestions are deliberately NOT on this API: 2-hop structure about a member belongs to the member, so "people you may know" renders only on the member's own account page.

Utility APIs — your data plane

Backend-to-backend, authenticated with your tenant API key (issued in your console). Same convention across graph, orgs, and tags. Rate-limited per key.

# the community's connection graph — member refs are per-community pgm_ values
curl -H "authorization: Bearer $PGX_KEY" https://<issuer>/api/graph
# → { "ok": true, "graph": { "nodes":[{"ref":"pgm_…","handle":"ava","degree":3}],
#       "edges":[{"a":"pgm_…","b":"pgm_…","weight":2}],
#       "hidden_private_count":1, "truncated":false } }

# form a connection from a DogTag tap
curl -X POST -H "authorization: Bearer $PGX_KEY" -H "content-type: application/json" \
  -d '{ "actor_user_id":"pgm_…", "tag_ref":"<tapped-tag>" }' \
  https://<issuer>/api/graph/connect

Also: GET/POST /api/orgs (list your clubs + effective providers / create one: { slug, name, login_providers? }), GET/PATCH /api/orgs/{slug} (club detail + its next scheduled events, source + sync time labeled — no member data / update { name?, login_providers? }), and POST /api/orgs/{slug}/clients ({ name, redirect_uris } — register an org-bound SSO client; POST only, there is no client listing here). All wrapped { ok: true, … }.

Eligibility rail & commerce

The fundraising primitive: a community authors gates (membership, tags, ranks, connections, club subtrees) and an external store learns only { eligible } — plus, on yes, a 5-minute EdDSA entitlement it verifies offline against the community JWKS. Never attributes, standing values, or the reason.

POST /api/providers/shopify/eligibility
Authorization: Bearer <tenant API key>          # issued in your community console
Content-Type: application/json

{ "member_token": "<the member's Pernox access token from your SSO login>",
  "product_gid":  "gid://shopify/Product/123456" }

# 404 { "error": "product_not_gated" }     product has no gate mapping
# 400 { "error": "member_token and product_gid required" }
# 401 / 429                                bad tenant API key / rate limited
# 200 { "eligible": false }                not eligible / missing eligibility
#                                          consent / token from another community
# 200 { "eligible": true,
#       "gate": "gold-drop",
#       "entitlement": "<5-min EdDSA JWT — verify offline against the
#                        community JWKS, then apply your discount/metafield>" }

POST /api/providers/stripe/checkout
Authorization: Bearer <tenant API key>
Content-Type: application/json

{ "member_token":  "<the member's Pernox access token from your SSO login>",
  "gate":          "gold-drop",
  "amount_cents":  2500,                      # integer > 0, usd
  "product_name":  "Gold drop tee",
  "success_url":   "https://your.site/thanks",
  "cancel_url":    "https://your.site/drop",
  "org_id":        "<club id>",               # optional: evaluate at a club
  "product_gid":   "gid://shopify/Product/…" }# optional

# 400 { "error": "member_token, gate, product_name, amount_cents (>0), success_url, cancel_url required" }
# 401 / 429                                bad tenant API key / rate limited
# 409 { "error": "payouts_not_ready" }     finish Stripe payout onboarding first
# 503 { "error": "stripe_not_configured" }
# 200 { "eligible": false }                not eligible / missing eligibility consent
# 200 { "eligible": true, "checkout_url": "<hosted Stripe Checkout — redirect the buyer>" }

Settlement: sales record PII-free on the community's ledger; its share auto-transfers via Stripe Connect; refunds reverse the transferred share at the sale-time rate.

Sponsorships & offers — prepaid access, not ads

Sponsors fund pools up front (settling like a sale: the community keeps 65% rising to 90% as lifetime volume grows; the platform's take credits the community's subscription). Members claim shareable references and pass them person-to-person — nothing is broadcast, every reach number is a community-set cap, and no cash ever flows to an individual: redemptions grant points into standing and a signed receipt the community's own storefronts honor as the discount.

Embeds — widgets for your own site

Small tenant-branded iframes your community's external sites can embed. The allowlist IS your client registry: a host origin may frame these only when it is registered as a redirect origin on one of your SSO clients (console → Developers). Widgets set no cookies, hold no session, and never persist a member token.

<script src="https://<community-host>/widget/v1/pernox.js"
        data-widget="drop" data-gate="<gate-slug>" data-org="<club-slug>"></script>
<!-- data-org (optional) scopes the gate check to one club inside the community -->
<!-- events: "pernox:ready", "pernox:state" (detail: locked|unlocked|unknown) -->

Host-side cost, honestly: a strict host CSP needs frame-src for the community host; the loader script additionally needs script-src for it. A bare <iframe> paste works with no script at all.

Campaign interest — pre-launch reserves

The reserve rail behind campaign showcase pages (first: Wear the League). An interest list, not an order book — no payment fields exist, emails are encrypted + blind-indexed, and a row counts as demand only after its single-use emailed token is clicked. Success responses are deliberately identical for new, repeated, and already-confirmed addresses.

Plans

The member cap counts distinct members (rolling up clubs). Invoices snapshot the plan held during the period, and a community's sponsorship take credits its metered plan fee (floored at $0).

Status