Global Player Passport (FIPJP)

The Global Passport lives in the FIPJP tenant and acts as the canonical cross-tenant view of a player. The GlobalPassport Beanie document carries a passport_id formatted FIPJP-YYYY-NNNNNN, a unique auth_identity_id linking back to the shared OAuth/OTP identity, personal details, and an embedded linked_licenses list with tenant_code, license_number, season, status, and last_verified_at per entry. Because everything is tenant-scoped to FIPJP, no national tenant ever stores the passport itself — they reference it indirectly through the auth identity.

Passport numbering is governed by FIPJPTenantConfig, a singleton that holds passport_number_format, next_passport_sequence (incremented atomically via $inc to avoid collisions under concurrency), photo_required, and photo_max_size_kb. Admin endpoints cover the lifecycle: POST /fipjp/passports creates a passport, GET /fipjp/passports/{id} retrieves it, POST /link-license attaches a national license, POST /verify-license verifies a linked license against the issuing national tenant (with a 24-hour cache to avoid hammering the source-of-truth API), and PATCH /status suspends or revokes. Two public verification endpoints — GET /public/passports/{id} and GET /public/passports/by-license?tenant_code&license_number — return privacy-safe data only (name, nationality, license status), explicitly omitting date of birth and photo, so visiting referees and event organisers can verify a player without leaking PII.

Automatic onboarding is implemented in passport_sync.py: link_local_license_to_passport() creates a passport on the player's first license issuance and appends to the linked_licenses list on subsequent issuances. The sync is fire-and-forget — if the FIPJP call fails, the national license issuance still succeeds, and the link is reconciled later. Each national TenantConfig carries fipjp_passport_sync_enabled (default true), fipjp_passport_sync_endpoint, and fipjp_m2m_credentials_secret_ref so M2M auth happens through Key Vault rather than configuration. A backfill job, backfill_global_passports(), iterates every active license across every national tenant and creates or updates passports per auth_identity; the job is idempotent so it can be re-run safely.