{"openapi":"3.1.0","info":{"title":"DUPR Backend APIs (Public)","description":"Public RESTful APIs accessible with external read-only tokens.","version":"v1.0.0"},"servers":[{"url":"https://api.dupr.com"}],"security":[{"bearerAuth":[]}],"paths":{"/subscription/active":{"post":{"tags":["Subscriptions Controller"],"operationId":"getSubscriptions","responses":{"200":{"description":"Returns a list of Subscription objects that indicate the level of access the user has to each resource","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicSubscriptionResponse"}}}}},"security":[{"bearerAuth":[]}]}},"/user/club/membership":{"get":{"tags":["User"],"operationId":"getClubMembership","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[{"bearerAuth":[]}]}},"/public/user/info":{"get":{"tags":["Public"],"summary":"Fetch basic user info for the bearer token holder","description":"Returns the authenticated user's DUPR ID and whichever PII fields the user has consented to share with the calling partner. For non-external bearer tokens (no clientId claim) only the DUPR ID is returned. Note: in-handler failures (e.g. inability to resolve the user or fetch consent) are surfaced as HTTP 200 with `status=FAILURE` in the body; real 401s come from the security filter and never reach the handler.","operationId":"getBasicInfo","responses":{"200":{"description":"Basic info envelope. Inspect `status` — SUCCESS carries `results[0]` with the basic info; FAILURE carries errors in `errors`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BasicInfoResult"}}}},"403":{"description":"Bearer token is missing, expired, malformed, or otherwise rejected by the auth filter chain. Body is the standard `{status, message}` envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWrapper"}}}},"404":{"description":"The user referenced by the token cannot be resolved (e.g. deleted after the token was issued).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWrapper"}}}},"500":{"description":"Unexpected server error before the handler could respond.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorWrapper"}}}}},"security":[{"bearerAuth":[]}]}},"/auth/{version}/refresh":{"get":{"tags":["Authentication"],"summary":"Refresh an access token (supports both regular and read-only tokens)","description":"Takes a refresh token in the `x-refresh-token` header. v2.0+ returns a full `AuthResponse`; v1.0 returns only the newly issued access token as a raw string wrapped in the standard envelope (see `RefreshedTokenWrapper`). The refresh token itself is the credential — no bearer `Authorization` header is required.","operationId":"refreshAccessToken","parameters":[{"name":"version","in":"path","required":true,"schema":{"type":"string","default":"v2.0"}},{"name":"x-refresh-token","in":"header","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token refreshed successfully. v2.0+ response shape shown below; v1.0 returns the access token as a raw string under `result`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthResponseWrapper"}}}},"400":{"description":"Refresh token is missing, malformed, expired, revoked, or does not correspond to an active user.","content":{"application/json":{"schema":{"type":"object"}}}},"500":{"description":"Unexpected server error while refreshing the token.","content":{"application/json":{"schema":{"type":"object"}}}}},"security":[{"bearerAuth":[]}]}}},"components":{"schemas":{"PublicEntitlement":{"type":"string","description":"Publicly documented entitlement values returned by /subscription/active","enum":["BASIC_L1","PREMIUM_L1","VERIFIED_L1","ULTIMATE_PICKLEBALL_LEAGUE_L1"]},"PublicEntitlements":{"type":"object","description":"Entitlements the user holds, keyed by resource","properties":{"tournaments":{"type":"array","description":"Entitlements for organized, rated play — leagues and tournaments (but not necessarily other events such as open play). Absence of BASIC_L1 means the user is restricted from play.","example":["BASIC_L1","PREMIUM_L1","VERIFIED_L1"],"items":{"$ref":"#/components/schemas/PublicEntitlement"}},"merchandise":{"type":"array","description":"Entitlements for merchandise discounts and offers. PREMIUM_L1 indicates the user is eligible for member merchandise pricing.","example":["PREMIUM_L1"],"items":{"$ref":"#/components/schemas/PublicEntitlement"}}},"required":["merchandise","tournaments"]},"PublicSubscription":{"type":"object","properties":{"status":{"type":"string","deprecated":true,"description":"This field should not be used; please check for specific entitlements","example":"active"},"displayName":{"type":"string","description":"A human readable display name for the subscription","example":"DUPR+"},"entitlements":{"$ref":"#/components/schemas/PublicEntitlements","description":"Entitlements the user holds, keyed by resource (operation -> capabilities)"}},"required":["displayName","entitlements","status"]},"PublicSubscriptionResponse":{"type":"object","properties":{"subscriptions":{"type":"array","description":"A list of subscription descriptors. Descriptors will contain a list of operations and entitlements, which can be used to gate 3rd party features","items":{"$ref":"#/components/schemas/PublicSubscription"}}},"required":["subscriptions"]},"BasicInfo":{"type":"object","properties":{"duprId":{"type":"string","example":"GB0NV05E"},"fullName":{"type":"string","description":"Full name (requires consent)","example":"John Doe"},"gender":{"type":"string","description":"Gender (requires consent)","example":"MALE"},"birthYear":{"type":"integer","format":"int32","description":"Birth year (required consent field)","example":1990},"location":{"type":"string","description":"Location (requires consent)","example":"Center Valley, PA, US"}},"required":["duprId"]},"BasicInfoResult":{"type":"object","description":"Envelope returned by GET /public/user/info.","properties":{"status":{"type":"string","enum":["SUCCESS","FAILURE","REDIRECT","PARTIAL"]},"results":{"type":"array","items":{"$ref":"#/components/schemas/BasicInfo"}},"errors":{"type":"array","items":{"$ref":"#/components/schemas/Error"}}},"required":["errors","results","status"]},"Error":{"type":"object","properties":{"message":{"type":"string"}},"required":["message"]},"ErrorWrapper":{"type":"object","description":"Standard error envelope returned by the auth filter chain and by explicit 403/404/500 responses on partner-facing endpoints. Mirrors the runtime `Wrapper` type — `{status, message}` — with `status = FAILURE`.","properties":{"status":{"type":"string","enum":["SUCCESS","FAILURE","REDIRECT","PARTIAL"]},"message":{"type":"string","example":"No active consent for this partner. The user must re-grant consent."}},"required":["status"]},"AccountBanned":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"AccountRestricted":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"ActionDetail":{"type":"object","description":"Structured detail explaining one required action.","discriminator":{"propertyName":"type","mapping":{"feature-quota":"#/components/schemas/FeatureQuotaActionDetail"}},"oneOf":[{"$ref":"#/components/schemas/FeatureQuotaActionDetail"}],"properties":{"type":{"type":"string","description":"Discriminator for the detail type."}},"required":["type"]},"ActiveSetFullBlockReason":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaBlockReason"},{"type":"object","properties":{"capacity":{"type":"integer","format":"int64","description":"Maximum resources held at once."},"heldResourceIds":{"type":"array","description":"Resource ids currently occupying the set.","items":{"type":"string"}},"reset":{"$ref":"#/components/schemas/TemporalMarker","description":"When the earliest-expiring entry frees a slot."}}}],"description":"Every concurrent slot is occupied; releasing one frees capacity.","required":["capacity","featureKey","heldResourceIds","reset","type"]},"AddressResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":12385789},"addressLine":{"type":"string","example":"Apartment, Room, PO Box numbers (optional)"},"shortAddress":{"type":"string","example":"Center Valley, PA, US"},"formattedAddress":{"type":"string","example":5800},"latitude":{"type":"number","example":33.194791},"longitude":{"type":"number","example":-117.048582},"placeId":{"type":"string"},"precision":{"type":"string"},"status":{"type":"string"},"types":{"type":"string"},"create":{"type":"string","format":"date-time"}},"required":["create","formattedAddress","latitude","longitude","shortAddress"]},"AtTemporalMarker":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemporalMarker"},{"type":"object","properties":{"atEpochSeconds":{"type":"integer","format":"int64","description":"The instant, epoch seconds.","example":1785000000}}}],"description":"A fixed instant.","required":["atEpochSeconds","type"]},"AuthResponse":{"type":"object","properties":{"accessToken":{"type":"string","example":"eyJhbGciOiJSUzUxMiJ9."},"refreshToken":{"type":"string","example":"eyJhbGciOiJSUzUxMiJ9."},"user":{"$ref":"#/components/schemas/UserResponse"},"challengeToken":{"type":"string","description":"Challenge token for 2FA verification (5-minute TTL)","example":"eyJhbGciOiJSUzUxMiJ9."},"twoFactorRequired":{"type":"boolean","description":"True when 2FA verification is required to complete login"},"twoFactorSetupRequired":{"type":"boolean","description":"True when user should be prompted to set up 2FA (post-login enforcement)"},"requiredActions":{"type":"array","description":"Actions the user must complete before accessing protected APIs. Present only when the user has outstanding required actions.","items":{"type":"string","description":"Actions or denial reasons enforced before API access","enum":["TWO_FACTOR_SETUP","TWO_FACTOR_CHALLENGE","PHONE_VERIFICATION","EMAIL_VERIFICATION","SUBSCRIPTION_REQUIRED","PASSWORD_RESET_REQUIRED","STRONG_MFA_SETUP","ACCOUNT_BANNED","ACCOUNT_RESTRICTED","BOT_FLAGGED","LIMITED_VIEW"]},"uniqueItems":true},"requirements":{"type":"array","description":"The rich, URN-tagged form of [requiredActions] — clients should branch on each requirement's `type` URN. Projected from the same actions; present alongside them during the expand→migrate window.","items":{"oneOf":[{"$ref":"#/components/schemas/AccountBanned"},{"$ref":"#/components/schemas/AccountRestricted"},{"$ref":"#/components/schemas/BotFlagged"},{"$ref":"#/components/schemas/EmailVerification"},{"$ref":"#/components/schemas/FeatureQuota"},{"$ref":"#/components/schemas/LimitedView"},{"$ref":"#/components/schemas/PasswordResetRequired"},{"$ref":"#/components/schemas/PhoneVerification"},{"$ref":"#/components/schemas/StrongMfaSetup"},{"$ref":"#/components/schemas/SubscriptionRequired"},{"$ref":"#/components/schemas/TwoFactorChallenge"},{"$ref":"#/components/schemas/TwoFactorSetup"}]}}}},"AuthResponseWrapper":{"type":"object","description":"Envelope returned by /auth/{version}/refresh for v2.0+ (full AuthResponse).","properties":{"status":{"type":"string","enum":["SUCCESS","FAILURE","REDIRECT","PARTIAL"]},"message":{"type":"string"},"result":{"$ref":"#/components/schemas/AuthResponse"}},"required":["status"]},"BotFlagged":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"Email":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"EmailVerification":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"FeatureNotGrantedBlockReason":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaBlockReason"}],"description":"No rule grants this feature to the user.","required":["featureKey","type"]},"FeatureQuota":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"},{"type":"object","properties":{"detail":{"$ref":"#/components/schemas/FeatureQuotaActionDetail"}}}],"required":["detail","type"]},"FeatureQuotaActionDetail":{"type":"object","allOf":[{"$ref":"#/components/schemas/ActionDetail"},{"type":"object","properties":{"featureKey":{"type":"string","description":"Feature that blocked."},"quotaKind":{"type":"string","description":"Whether the feature counts usages or caps a held set.","enum":["USAGE_COUNT","ACTIVE_SET"]},"reason":{"$ref":"#/components/schemas/QuotaBlockReason","description":"Machine-readable reason, with the relevant numbers."},"metadata":{"type":"object","additionalProperties":{"type":"string"},"description":"Grant metadata echoed verbatim (e.g. superwall_placement)."}}}],"description":"Why a metered feature blocked this request.","required":["featureKey","metadata","quotaKind","reason","type"]},"LimitedQuotaLimit":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaLimit"},{"type":"object","properties":{"max":{"type":"integer","format":"int64","description":"Maximum usages (or concurrently-held resources)."}}}],"description":"A finite cap within the grant's window.","required":["max","type"]},"LimitedView":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"NeverTemporalMarker":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemporalMarker"}],"description":"Nothing pending — no reset or no expiry.","required":["type"]},"PasswordResetRequired":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"},{"type":"object","properties":{"resetToken":{"type":"string"}}}],"required":["type"]},"Phone":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"PhoneVerification":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"PlayerRatingResponse":{"type":"object","properties":{"singles":{"type":"string","example":4.125},"singlesVerified":{"type":"string","example":4.1},"singlesProvisional":{"type":"boolean"},"singlesReliabilityScore":{"type":"number","example":10},"doubles":{"type":"string","example":2.864},"doublesVerified":{"type":"string","example":2.75},"doublesProvisional":{"type":"boolean"},"doublesReliabilityScore":{"type":"number","example":10},"defaultRating":{"type":"string","enum":["SINGLES","DOUBLES"],"example":"DOUBLES"},"provisionalRatings":{"$ref":"#/components/schemas/ProvisionalRating"}}},"ProvisionalRating":{"type":"object","properties":{"singlesRating":{"type":"number","format":"float","example":3.5},"doublesRating":{"type":"number","format":"float","example":3.5},"coach":{"$ref":"#/components/schemas/RatingCoach","example":"{ id: 12345, metadata: { name: example }}"}}},"Push":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"QuotaBlockReason":{"type":"object","description":"Machine-readable reason a metered request was blocked. Carries no display copy.","discriminator":{"propertyName":"type","mapping":{"QUOTA_EXCEEDED":"#/components/schemas/QuotaExceededBlockReason","ACTIVE_SET_FULL":"#/components/schemas/ActiveSetFullBlockReason","FEATURE_NOT_GRANTED":"#/components/schemas/FeatureNotGrantedBlockReason","RESOURCE_REQUIRED":"#/components/schemas/ResourceRequiredBlockReason"}},"oneOf":[{"$ref":"#/components/schemas/QuotaExceededBlockReason"},{"$ref":"#/components/schemas/ActiveSetFullBlockReason"},{"$ref":"#/components/schemas/FeatureNotGrantedBlockReason"},{"$ref":"#/components/schemas/ResourceRequiredBlockReason"}],"properties":{"type":{"type":"string","description":"Discriminator for the block reason."},"featureKey":{"type":"string","description":"Feature the block applies to."}},"required":["featureKey","type"]},"QuotaExceededBlockReason":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaBlockReason"},{"type":"object","properties":{"limit":{"$ref":"#/components/schemas/QuotaLimit","description":"The cap that was hit."},"used":{"type":"integer","format":"int64","description":"Usages consumed in the current window."},"reset":{"$ref":"#/components/schemas/TemporalMarker","description":"When the allotment next replenishes."}}}],"description":"The usage allotment is spent for the current window.","required":["featureKey","limit","reset","type","used"]},"QuotaLimit":{"type":"object","description":"How much of a feature a cohort is granted.","discriminator":{"propertyName":"type","mapping":{"unlimited":"#/components/schemas/UnlimitedQuotaLimit","limited":"#/components/schemas/LimitedQuotaLimit"}},"oneOf":[{"$ref":"#/components/schemas/UnlimitedQuotaLimit"},{"$ref":"#/components/schemas/LimitedQuotaLimit"}],"properties":{"type":{"type":"string","description":"Discriminator for the limit type."}},"required":["type"]},"RatingCoach":{"type":"object","properties":{"id":{"type":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string"}}},"required":["metadata"]},"Recovery":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"RequiredAction":{"type":"object","description":"A URN-identified requirement the caller must satisfy.","discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string","description":"URN discriminator identifying the required action."}},"required":["type"]},"ResourceRequiredBlockReason":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaBlockReason"},{"type":"object","properties":{"param":{"type":"string","description":"Name of the missing path variable."}}}],"description":"A resource-scoped feature was called without its resource id.","required":["featureKey","param","type"]},"RoleResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":424255123},"role":{"type":"string","example":"PLAYER"},"permissions":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"},"uniqueItems":true},"example":{"USER":["VIEW","MODIFY"],"TOURNAMENT":["OWN_VIEW","OWN_MODIFY","OWN_DELETE"]}}},"required":["id","permissions","role"]},"RollingRefillTemporalMarker":{"type":"object","allOf":[{"$ref":"#/components/schemas/TemporalMarker"},{"type":"object","properties":{"nextAtEpochSeconds":{"type":"integer","format":"int64","description":"When at least one unit frees up, epoch seconds.","example":1785000000}}}],"description":"Partial refill when the oldest in-window usage ages out.","required":["nextAtEpochSeconds","type"]},"SecondFactorKind":{"type":"object","description":"A URN-identified second-factor method.","discriminator":{"propertyName":"type"},"properties":{"type":{"type":"string","description":"URN discriminator identifying the second-factor method."}},"required":["type"]},"Sms":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"StrongMfaSetup":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"},{"type":"object","properties":{"allowedMethods":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Email"},{"$ref":"#/components/schemas/Phone"},{"$ref":"#/components/schemas/Push"},{"$ref":"#/components/schemas/Recovery"},{"$ref":"#/components/schemas/Sms"},{"$ref":"#/components/schemas/Totp"},{"$ref":"#/components/schemas/Webauthn"}]}}}}],"required":["allowedMethods","type"]},"SubscriptionRequired":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"TemporalMarker":{"type":"object","description":"A computed instant for a quota field (reset or expiry), or never.","discriminator":{"propertyName":"type","mapping":{"never":"#/components/schemas/NeverTemporalMarker","at":"#/components/schemas/AtTemporalMarker","rolling-refill":"#/components/schemas/RollingRefillTemporalMarker"}},"oneOf":[{"$ref":"#/components/schemas/NeverTemporalMarker"},{"$ref":"#/components/schemas/AtTemporalMarker"},{"$ref":"#/components/schemas/RollingRefillTemporalMarker"}],"properties":{"type":{"type":"string","description":"Discriminator for the marker type."}},"required":["type"]},"Totp":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]},"TwoFactorChallenge":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"},{"type":"object","properties":{"challengeToken":{"type":"string"},"methods":{"type":"array","items":{"oneOf":[{"$ref":"#/components/schemas/Email"},{"$ref":"#/components/schemas/Phone"},{"$ref":"#/components/schemas/Push"},{"$ref":"#/components/schemas/Recovery"},{"$ref":"#/components/schemas/Sms"},{"$ref":"#/components/schemas/Totp"},{"$ref":"#/components/schemas/Webauthn"}]}},"defaultMethod":{"oneOf":[{"$ref":"#/components/schemas/Email"},{"$ref":"#/components/schemas/Phone"},{"$ref":"#/components/schemas/Push"},{"$ref":"#/components/schemas/Recovery"},{"$ref":"#/components/schemas/Sms"},{"$ref":"#/components/schemas/Totp"},{"$ref":"#/components/schemas/Webauthn"}]}}}],"required":["challengeToken","defaultMethod","methods","type"]},"TwoFactorSetup":{"allOf":[{"$ref":"#/components/schemas/RequiredAction"}],"required":["type"]},"UnlimitedQuotaLimit":{"type":"object","allOf":[{"$ref":"#/components/schemas/QuotaLimit"}],"description":"No cap — the meter short-circuits and never blocks.","required":["type"]},"UserPreferencesResponse":{"type":"object","properties":{"enableSms":{"type":"boolean","example":true},"enableEmail":{"type":"boolean","example":true},"enablePush":{"type":"boolean","example":true},"enablePrivacy":{"type":"boolean","example":true},"enableNewsletter":{"type":"boolean","example":true}},"required":["enableEmail","enableNewsletter","enablePrivacy","enablePush","enableSms"]},"UserResponse":{"type":"object","properties":{"id":{"type":"integer","format":"int64","example":45785789},"fullName":{"type":"string","example":"John Doe"},"firstName":{"type":"string","example":"John"},"lastName":{"type":"string","example":"Doe"},"username":{"type":"string","example":"X AE A-XII"},"displayUsername":{"type":"boolean","example":true},"isoCode":{"type":"string","example":"US"},"phone":{"type":"string","example":"+14445785789"},"isValidPhone":{"type":"boolean"},"email":{"type":"string","example":"user@exmaple.com"},"isValidEmail":{"type":"boolean"},"imageUrl":{"type":"string","example":"https://dupr-dev.s3.us-east-1.amazonaws.com/users/profile.jpg"},"referralCode":{"type":"string","example":"GB0NV05E"},"birthdate":{"type":"string","format":"date","example":"yyyy-MM-dd"},"gender":{"type":"string","enum":["MALE","FEMALE"]},"hand":{"type":"string","enum":["RIGHT","LEFT","BOTH","NONE"]},"role":{"$ref":"#/components/schemas/RoleResponse"},"stats":{"$ref":"#/components/schemas/PlayerRatingResponse"},"addresses":{"type":"array","items":{"$ref":"#/components/schemas/AddressResponse"}},"active":{"type":"boolean"},"userPreferences":{"$ref":"#/components/schemas/UserPreferencesResponse"},"paddleBrand":{"type":"string","example":"Selkirk Vanguard Hybrid S2"},"shoeBrand":{"type":"string","example":"Nike"},"apparelBrand":{"type":"string","example":"Puma"},"preferredBall":{"type":"string","example":"Balls"},"preferredSide":{"type":"string","enum":["RIGHT","LEFT","EITHER"],"example":"LEFT/RIGHT/EITHER"},"restricted":{"type":"boolean","example":true},"lucraConnected":{"type":"boolean","example":true},"createdEpochSeconds":{"type":"integer","format":"int64","description":"Account-creation timestamp from users.created, epoch seconds.","example":1714032000},"validEmail":{"type":"boolean","writeOnly":true},"validPhone":{"type":"boolean","writeOnly":true}},"required":["active","email","firstName","fullName","id","lastName"]},"Webauthn":{"allOf":[{"$ref":"#/components/schemas/SecondFactorKind"}],"required":["type"]}},"securitySchemes":{"bearerAuth":{"type":"http","in":"header","scheme":"bearer","bearerFormat":"JWT"}}}}