basketball-api

Multi-tenant AAU basketball program management API. Handles registration (via Stripe webhooks), roster management, coach onboarding, and automated communications (via Gmail) for AAU basketball programs.

First Client

Westside Kings & Queens (Marcus Draney) — AAU basketball in Farmington, NM.

Live site: https://basketball-api.tail5b443a.ts.net

Quick Links for Marcus

What	Link
Coach signup (share with ALL coaches)	https://basketball-api.tail5b443a.ts.net/coach/signup
Parent registration (walk-up / QR)	https://basketball-api.tail5b443a.ts.net/register
Stripe test coupon (100% off, 5 uses)	TESTFREE
Tryout payment link ($30)	https://buy.stripe.com/aFa8wRbky5KwgL0bI60VO01

Endpoints

Method	Path	Auth	Description
GET	/healthz	None	Health check
GET	/register	None	Parent registration (email gate → form → waiver)
GET	/register?token=xxx	None	Pre-filled registration from email link
POST	/webhooks/stripe	Stripe sig	Stripe webhook receiver
GET	/coach/signup	None	Coach contractor agreement + Stripe Connect
GET	/coach/onboard?token=xxx	None	Coach onboarding (token-based, legacy)
GET	/tenants/{slug}/roster	None	Roster JSON API
GET	/tenants/{slug}/roster/view	None	Roster HTML page
POST	/admin/generate-tokens	Admin JWT	Generate registration tokens for paid parents
POST	/admin/invite-coach	Admin JWT	Create individual coach invite

Architecture

Stripe Payment Link → Stripe webhook → basketball-api → Postgres
                                            ↓
                                    gmail-sdk → draneylucas@gmail.com (POC)
                                               westsidebasketball@gmail.com (production)

Deployment

Deployed to pal-e k3s cluster via Forgejo → Woodpecker CI → Harbor → ArgoCD.

Setup

Prerequisites

• basketball-api-secrets K8s secret with: postgres-password, stripe-webhook-secret, stripe-api-key
• BASKETBALL_KEYCLOAK_REALM_URL env var pointing to the Keycloak realm (e.g. https://keycloak.tail5b443a.ts.net/realms/pal-e)
• Gmail OAuth token for tenant (via gmail-sdk authorize flow)
• Tenant seeded in DB: INSERT INTO tenants (slug, name, contact_email, gmail_account) VALUES ('westside-kings-queens', 'Westside Kings & Queens', 'westsidebasketball@gmail.com', 'draneylucas')

Local Development

pip install -e ".[dev]"
export BASKETBALL_DATABASE_URL=postgresql://basketball:basketball@localhost:5432/basketball
alembic upgrade head
python scripts/seed.py
python -m basketball_api.main

Auth

Protected endpoints require a Keycloak-issued JWT (RS256). The API validates tokens against the realm's public JWKS endpoint (BASKETBALL_KEYCLOAK_REALM_URL). No client secret is needed -- only the RS256 public keys are used for verification. Realm roles (e.g. admin) are extracted from the realm_access.roles claim.