# PlayerPal Docs

> One player identity and loyalty layer across casinos, game providers and affiliates — without personal data.

## Pages

- [ADR NNNN: Title](https://docs-internal.playerpal.io/docs/adr-template.md)
- [Insights and Ask](https://docs-internal.playerpal.io/docs/analytics/insights.md): How PlayerPal turns partner KPIs into ranked, explainable insights and answers common questions, using fixed rules rather than a language model.
- [Metric dictionary](https://docs-internal.playerpal.io/docs/analytics/metrics.md): Every PlayerPal partner KPI, with its ID, definition, grain, source, time window, currency and privacy rule.
- [Partner analytics](https://docs-internal.playerpal.io/docs/analytics/overview.md): What operators and game providers can see about their players in PlayerPal, how it is protected, and where to get it.
- [Privacy thresholds](https://docs-internal.playerpal.io/docs/analytics/privacy-thresholds.md): The account floor, peer floor and dominance rules that keep PlayerPal analytics anonymous, and what a suppressed value looks like.
- [Partner API authentication](https://docs-internal.playerpal.io/docs/api/hmac-signing.md)
- [Partner fact ingestion (`POST /v1/ingest`)](https://docs-internal.playerpal.io/docs/api/ingest.md)
- [Partner KPI API](https://docs-internal.playerpal.io/docs/api/kpis.md)
- [Architecture](https://docs-internal.playerpal.io/docs/architecture.md)
- [Authentication](https://docs-internal.playerpal.io/docs/authentication.md)
- [Authorization](https://docs-internal.playerpal.io/docs/authorization.md)
- [Semantic / conventional commits](https://docs-internal.playerpal.io/docs/commits.md)
- [Contributing to the docs](https://docs-internal.playerpal.io/docs/contributing/docs.md): How to write, label, check and preview PlayerPal documentation, by hand or with AI coding tools.
- [Writing style and page kit](https://docs-internal.playerpal.io/docs/contributing/style.md): Voice, page structure, components and the public-page rules for PlayerPal documentation.
- [Data model](https://docs-internal.playerpal.io/docs/data-model.md)
- [ADR 0001. Generic Party Model](https://docs-internal.playerpal.io/docs/decisions/0001-generic-party-model.md)
- [ADR 0002. Random Pairwise External IDs (not derived from internal UUID)](https://docs-internal.playerpal.io/docs/decisions/0002-random-pairwise-external-ids.md)
- [ADR 0003. Authenticate at a Boundary Point, Not Per-Action](https://docs-internal.playerpal.io/docs/decisions/0003-session-jwt-at-boundary.md)
- [ADR 0004. Async-First Ingestion (Control Plane vs. Data Plane)](https://docs-internal.playerpal.io/docs/decisions/0004-async-first-ingestion.md)
- [ADR 0005. Phased Event-Log Infrastructure](https://docs-internal.playerpal.io/docs/decisions/0005-phased-event-log-infrastructure.md)
- [ADR 0006. Large Batches via Object Storage + Manifest, Not One Giant HTTP Payload](https://docs-internal.playerpal.io/docs/decisions/0006-batch-ingestion-via-object-storage.md)
- [ADR 0007. Versioned/Snapshotted Campaign Configuration](https://docs-internal.playerpal.io/docs/decisions/0007-versioned-campaign-configuration.md)
- [ADR 0008. At-Least-Once Delivery + Idempotent Processing (Not Exactly-Once)](https://docs-internal.playerpal.io/docs/decisions/0008-at-least-once-plus-idempotency.md)
- [ADR 0009. Mandatory One-Time Link Before Any Data Reaches PlayerPal](https://docs-internal.playerpal.io/docs/decisions/0009-mandatory-one-time-link-before-data-flows.md)
- [ADR 0010. Linking to an Existing PlayerPal Account Unifies Relationships](https://docs-internal.playerpal.io/docs/decisions/0010-linking-unifies-no-separate-claim.md)
- [ADR 0011. IAM Authenticates; PlayerPal Owns the Identity Graph](https://docs-internal.playerpal.io/docs/decisions/0011-iam-authenticates-playerpal-owns-identity.md)
- [ADR 0012. Never Receive or Store Player Email, Name or Telephone](https://docs-internal.playerpal.io/docs/decisions/0012-never-receive-player-pii.md)
- [ADR 0013. Typed Pairwise Aliases (`pp_plr_`, `pp_plr_opr_`, `pp_plr_prv_`, …)](https://docs-internal.playerpal.io/docs/decisions/0013-typed-pairwise-aliases.md)
- [ADR 0014. Provider Aliases Are Provider-Operator Scoped](https://docs-internal.playerpal.io/docs/decisions/0014-provider-operator-alias-scope.md)
- [ADR 0015. PlayerPal Is an Async Loyalty Sidecar](https://docs-internal.playerpal.io/docs/decisions/0015-async-loyalty-sidecar.md)
- [ADR 0016. BFF Cookie Sessions and Machine OAuth](https://docs-internal.playerpal.io/docs/decisions/0016-bff-cookies-and-machine-oauth.md)
- [ADR 0017. Operator Linking via Signed Assertion and PlayerPal Popup](https://docs-internal.playerpal.io/docs/decisions/0017-operator-assertion-popup-linking.md)
- [ADR 0018. URL-Isolated Portals, No In-Product Role Picker](https://docs-internal.playerpal.io/docs/decisions/0018-url-isolated-portals.md)
- [ADR 0019. Scoped Bootstrap Proofs and Controlled Merge](https://docs-internal.playerpal.io/docs/decisions/0019-scoped-bootstrap-proofs-controlled-merge.md)
- [ADR 0020. Assurance Levels A0-A3; Password-Only Is Provisional](https://docs-internal.playerpal.io/docs/decisions/0020-assurance-levels-provisional-password.md)
- [ADR 0021. NestJS Control Plane + ZITADEL Local POC (Google IdP)](https://docs-internal.playerpal.io/docs/decisions/0021-nestjs-zitadel-local-poc.md)
- [ADR 0022. Official ZITADEL Login App Fork for Portal Sign-In](https://docs-internal.playerpal.io/docs/decisions/0022-official-login-app-fork.md)
- [ADR 0023. TypeORM Owns Nest Data Access and DDL](https://docs-internal.playerpal.io/docs/decisions/0023-typeorm-data-layer.md)
- [ADR 0024. Nest-Owned Portal Auth (Session API + Social IdP Intents)](https://docs-internal.playerpal.io/docs/decisions/0024-nest-owned-portal-auth.md)
- [ADR 0025. Provider Launch Sessions and PlayerPal Widget Distribution](https://docs-internal.playerpal.io/docs/decisions/0025-provider-launch-sessions-and-widget-distribution.md)
- [ADR 0026. Random Analytics Subject and Provider-Global Cohort (not alias)](https://docs-internal.playerpal.io/docs/decisions/0026-analytics-subject-and-provider-cohort.md)
- [ADR 0027. Mint aliases at link complete for listed integrations](https://docs-internal.playerpal.io/docs/decisions/0027-alias-provisioning-at-link.md)
- [ADR 0028. v1 recovery is codes, passkeys, and linked factors](https://docs-internal.playerpal.io/docs/decisions/0028-v1-recovery-without-operator-assist.md)
- [ADR 0029. Application-native authorization until a second service needs shared policy](https://docs-internal.playerpal.io/docs/decisions/0029-application-native-authorization.md)
- [ADR 0030. Unlink and Delete Account live on the PlayerPal Account](https://docs-internal.playerpal.io/docs/decisions/0030-unlink-delete-on-playerpal-account.md)
- [ADR 0031. Group Connected partners; confirm names the cascade](https://docs-internal.playerpal.io/docs/decisions/0031-account-connection-groups.md)
- [ADR 0032. Demo Bucks unlink notice and alias reconcile](https://docs-internal.playerpal.io/docs/decisions/0032-unlink-partner-notice.md)
- [ADR 0033. Partner KPI Platform: Visibility Tiers, Anonymous Comparison, Cube Behind Nest](https://docs-internal.playerpal.io/docs/decisions/0033-partner-kpi-platform.md)
- [ADR 0034. Documentation site: Docusaurus, OpenAPI, Scalar; internal first](https://docs-internal.playerpal.io/docs/decisions/0034-documentation-site.md)
- [Architecture Decision Records](https://docs-internal.playerpal.io/docs/decisions.md)
- [Authenticate API calls](https://docs-internal.playerpal.io/docs/developers/authentication.md): How partners authenticate with PlayerPal - HMAC request signing, OAuth client-credentials tokens, the integration key, scopes, key rotation and auth errors.
- [Design for availability](https://docs-internal.playerpal.io/docs/developers/availability.md): Casino login, game launch, wagering, settlement and payouts never wait on PlayerPal. How to integrate asynchronously with an outbox so play continues during an outage.
- [Changelog](https://docs-internal.playerpal.io/docs/developers/changelog.md): Changes to the PlayerPal Partner API, newest first.
- [Send daily facts](https://docs-internal.playerpal.io/docs/developers/fact-ingest.md): Send pseudonymous daily facts to POST /v1/ingest using four versioned schemas, read the batch receipt, and correct data safely.
- [Idempotency, retries and errors](https://docs-internal.playerpal.io/docs/developers/idempotency-and-errors.md): What PlayerPal deduplicates on, how to retry safely, the error body format and every partner API error code by endpoint family.
- [Developers](https://docs-internal.playerpal.io/docs/developers.md): Integrate with PlayerPal as an operator or game provider. Guides, code samples in six languages and the Partner API reference.
- [Read KPIs](https://docs-internal.playerpal.io/docs/developers/kpi-api.md): Read your own KPIs, breakdowns, network comparisons, benchmarks, cohorts, funnels and insights from /v1/kpis, with privacy suppression built in.
- [Link players](https://docs-internal.playerpal.io/docs/developers/linking-players.md): Connect a player at your casino or game to PlayerPal with a signed link intent, a PlayerPal-hosted consent popup and a one-time result exchange, and receive a pseudonymous alias.
- [Onboard as a partner](https://docs-internal.playerpal.io/docs/developers/onboarding.md): How an operator or game provider goes from signed up to live with PlayerPal - what PlayerPal provides, what you build, environments and the go-live checklist.
- [Quickstart](https://docs-internal.playerpal.io/docs/developers/quickstart.md): Sign a request, send your first fact batch to PlayerPal, check the receipt and read a KPI back.
- [Send player activity](https://docs-internal.playerpal.io/docs/developers/sending-activity.md): Report settled game rounds for linked players to PlayerPal as JSON batches or bulk file uploads, with per-batch idempotency and asynchronous processing.
- [Player link notices](https://docs-internal.playerpal.io/docs/developers/webhooks.md): The events PlayerPal sends to partners, the player link notice payload, how to authenticate and answer it, and how to reconcile alias status when a notice is missed.
- [Embed the PlayerPal widget](https://docs-internal.playerpal.io/docs/developers/widget.md): Load the PlayerPal widget into your game page from a versioned, integrity-checked release, hand it a launch session, and let players connect and see that they are earning.
- [Identity](https://docs-internal.playerpal.io/docs/identity.md)
- [Ingestion and availability](https://docs-internal.playerpal.io/docs/ingestion-and-availability.md)
- [KPIs](https://docs-internal.playerpal.io/docs/kpis.md)
- [Linking and bootstrap](https://docs-internal.playerpal.io/docs/linking-and-bootstrap.md)
- [Loyalty](https://docs-internal.playerpal.io/docs/loyalty.md)
- [Neon Nexus integration](https://docs-internal.playerpal.io/docs/neon-nexus-integration.md)
- [Neon Nexus play-money mathematics](https://docs-internal.playerpal.io/docs/neon-nexus-math.md)
- [Neon Nexus presentation (provider-game-demo)](https://docs-internal.playerpal.io/docs/neon-nexus-presentation.md)
- [Neon Nexus crash recovery](https://docs-internal.playerpal.io/docs/neon-nexus-recovery.md)
- [Neon Nexus three-mode verification](https://docs-internal.playerpal.io/docs/neon-nexus-three-mode.md)
- [Open questions](https://docs-internal.playerpal.io/docs/open-questions.md)
- [Portals](https://docs-internal.playerpal.io/docs/portals.md)
- [Business value](https://docs-internal.playerpal.io/docs/product/business-value.md): The problem PlayerPal addresses, how its design creates value across the network, and what is built today.
- [Capabilities](https://docs-internal.playerpal.io/docs/product/capabilities.md): What PlayerPal offers today, what is in development and what is planned, grouped by area.
- [Frequently asked questions](https://docs-internal.playerpal.io/docs/product/faq.md): Answers to the questions operators, game providers, affiliates, developers and investors ask most about PlayerPal.
- [For affiliates](https://docs-internal.playerpal.io/docs/product/for-affiliates.md): What PlayerPal supports for affiliates today, what is in development, and what has not been decided.
- [For game providers](https://docs-internal.playerpal.io/docs/product/for-game-providers.md): What PlayerPal gives a game provider, how provider Aliases are scoped per casino, and how the integration stays off the game path.
- [For operators](https://docs-internal.playerpal.io/docs/product/for-operators.md): What PlayerPal gives a casino operator, what it never touches, and how the integration fits around your existing platform.
- [For reward partners](https://docs-internal.playerpal.io/docs/product/for-reward-partners.md): The intended role of reward partners in PlayerPal. Planned; not built yet.
- [Glossary](https://docs-internal.playerpal.io/docs/product/glossary.md): Short definitions of the terms used across PlayerPal's product and developer documentation.
- [How PlayerPal works](https://docs-internal.playerpal.io/docs/product/how-it-works.md): The end-to-end journey from player sign-up to Points and partner analytics, and exactly what data moves where.
- [What is PlayerPal](https://docs-internal.playerpal.io/docs/product/overview.md): One player identity and loyalty layer that works across casinos, game providers and affiliates, without holding players' personal data.
- [Player experience](https://docs-internal.playerpal.io/docs/product/player-experience.md): What a player sees and controls in PlayerPal, from sign-in and linking to Points, Unlink and Delete Account.
- [PlayerPal documentation](https://docs-internal.playerpal.io/docs.md)
- [Points and rewards](https://docs-internal.playerpal.io/docs/rewards/points-and-rewards.md): How players earn PlayerPal points from qualifying activity, how the points ledger works, and how the rewards shop will turn points into rewards.
- [Personal data](https://docs-internal.playerpal.io/docs/security-privacy/personal-data.md): What player data PlayerPal holds, which identifiers it uses, who can see what, and what is still undecided about retention.
- [Reward redemption lifecycle](https://docs-internal.playerpal.io/docs/shop/redemption-lifecycle.md): How the player shop turns points into rewards, as built in the in-browser demo server on feat/player-shop, and what is missing before it can run in the API.
- [Implementation status](https://docs-internal.playerpal.io/docs/status.md): What PlayerPal runs today, what is in progress or demo-only, and what is only proposed, with the evidence for each.
- [Privacy](https://docs-internal.playerpal.io/docs/trust/privacy.md): PlayerPal's privacy commitments for players and partners, what data it holds, who can see it, and what Unlink and Delete Account do.
- [Security](https://docs-internal.playerpal.io/docs/trust/security.md): How PlayerPal authenticates partners and players, limits each party to its own data, and keeps retries safe.

## API

- [Partner API (OpenAPI 3.1)](https://docs-internal.playerpal.io/openapi/partner.json)