User Management API Endpoints

Overview

Endpoints for user authentication, profile management, settings, subscriptions, and payment processing.

Endpoint Summary

Authentication

Endpoint Method Auth Description
/v1/users/authenticate POST None User login
/v1/users/register POST None User registration
/v1/users/refresh-token POST None Refresh JWT token
/v1/users/logout POST JWT User logout
/v1/users/reset-password POST None Request password reset
/v1/users/update-password PUT None Update password with token
/v1/users/passwords PUT JWT Change password
/v1/users/confirm-email PUT None Confirm email address
/v1/auth/google POST None Google OAuth sign-in
/v1/auth/mfa/setup POST JWT Setup MFA
/v1/auth/mfa/verify POST JWT Verify MFA code

User Profile

Endpoint Method Auth Description
/v1/users/details GET JWT Get user details
/v1/users/settings GET JWT Get user settings
/v1/users/settings PATCH JWT Update user settings
/v1/users/dataproviders GET JWT Get user data providers
/v1/users/dataproviders PATCH JWT Update data providers
/v1/users/{email}/memberships GET None Get user memberships

Subscriptions

Endpoint Method Auth Description
/v1/users/subscriptions GET JWT Get subscriptions
/v1/users/subscriptions POST JWT Create subscription
/v1/users/subscriptions/{id} PUT JWT Update subscription
/v1/users/subscriptions/{id}/cancel PUT JWT Cancel subscription
/v1/users/subscriptions/{id}/pause PUT JWT Pause subscription
/v1/users/subscriptions/{id}/unpause PUT JWT Resume subscription

Notifications

Endpoint Method Auth Description
/v1/devicetokens POST None Register device token
/v1/users/notifications/tokens/{token} POST JWT Add push token
/v1/users/notifications/tokens/{token}/update POST JWT Update push settings

Authentication Endpoints

1. POST /v1/users/authenticate

Description: Authenticates a user and returns JWT tokens.

Request Body:

{
  "username": "user@example.com",
  "password": "securepassword123"
}

Response: AuthenticateResponse

{
  "userId": "a1b2c3d4-...",
  "username": "user@example.com",
  "email": "user@example.com",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "dGhpcyBpcyBhIHJlZnJlc2g...",
  "expires": "2025-11-30T12:00:00Z",
  "expiresAt": "2025-11-30T12:00:00Z",
  "roles": ["user"],
  "subscription": {
    "plan": "premium",
    "status": "active"
  }
}

Error Responses:

Status Error Description
401 invalid_credentials Invalid username or password

2. POST /v1/users/register

Description: Registers a new user account.

Request Body:

{
  "username": "newuser",
  "email": "newuser@example.com",
  "password": "securepassword123",
  "marketingOptIn": true
}

Response: RegistrationResponse

{
  "userId": "a1b2c3d4-...",
  "username": "newuser",
  "email": "newuser@example.com",
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "message": "Registration successful"
}

Error Responses:

Status Error Description
400 identity_already_used Username or email already exists

3. POST /v1/users/refresh-token

Description: Refreshes an expired access token.

Headers:

Response: RefreshTokenResponse

{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "newRefreshToken...",
  "expires": "2025-11-30T12:00:00Z",
  "expiresAt": "2025-11-30T12:00:00Z"
}

4. POST /v1/users/reset-password

Description: Initiates password reset process via email.

Request Body:

{
  "email": "user@example.com"
}

Response: 204 No Content (success)

5. PUT /v1/users/update-password

Description: Updates password using reset token.

Request Body:

{
  "token": "reset-token-from-email",
  "password": "newSecurePassword123"
}

Response: 204 No Content (success)

6. PUT /v1/users/passwords

Description: Changes password for authenticated user.

Authentication: JWT required

Request Body:

{
  "currentPassword": "oldPassword",
  "newPassword": "newPassword123"
}

Response: 200 OK

7. POST /v1/auth/google

Description: Authenticates user via Google OAuth.

Request Body:

{
  "code": "google-oauth-authorization-code",
  "marketingOptInState": true
}

Response: RegistrationResponse (same as register)

8. POST /v1/auth/mfa/setup

Description: Initializes MFA setup for user.

Authentication: JWT required

Response: MfaSetupResponse

{
  "secretKey": "JBSWY3DPEHPK3PXP",
  "qrCodeUrl": "otpauth://totp/MyApp:user@example.com?secret=...",
  "backupCodes": ["code1", "code2", "code3", "code4", "code5"]
}

9. POST /v1/auth/mfa/verify

Description: Verifies MFA code.

Authentication: JWT required

Request Body:

{
  "code": "123456",
  "rememberDevice": true
}

Response: MfaVerificationResponse

{
  "isValid": true,
  "deviceToken": "device-trust-token",
  "expiresAt": "2025-12-29T12:00:00Z"
}

User Profile Endpoints

10. GET /v1/users/details

Description: Retrieves authenticated user details.

Authentication: JWT required

Response: UserDetailsResponse

{
  "userId": "a1b2c3d4-...",
  "username": "user123",
  "email": "user@example.com",
  "displayName": "John Doe",
  "avatar": "https://...",
  "createdAt": "2024-01-15T10:00:00Z",
  "subscription": {
    "plan": "premium",
    "status": "active",
    "expiresAt": "2026-01-15T10:00:00Z"
  }
}

11. GET /v1/users/settings

Description: Retrieves user settings and preferences.

Authentication: JWT required

Response: UserSettingsResponse

{
  "timezone": "America/New_York",
  "oddsFormat": "american",
  "notifications": {
    "email": true,
    "push": true,
    "sms": false
  },
  "theme": "dark",
  "language": "en"
}

12. PATCH /v1/users/settings

Description: Updates user settings.

Authentication: JWT required

Request Body:

{
  "timezone": "America/Los_Angeles",
  "oddsFormat": "decimal",
  "notifications": {
    "email": true,
    "push": false
  }
}

Response: 200 OK

Subscription Endpoints

13. GET /v1/users/subscriptions

Description: Retrieves user's subscription information.

Authentication: JWT required

Response: Subscription details

{
  "subscriptions": [
    {
      "id": "sub_123",
      "plan": "premium",
      "status": "active",
      "currentPeriodStart": "2025-11-01",
      "currentPeriodEnd": "2025-12-01",
      "cancelAtPeriodEnd": false
    }
  ]
}

14. POST /v1/users/subscriptions

Description: Creates a new subscription.

Authentication: JWT required

Request Body:

{
  "planId": "premium_monthly",
  "paymentMethodId": "pm_..."
}

Response: CreateSubscriptionResponse

15. PUT /v1/users/subscriptions/{subscriptionId}/cancel

Description: Cancels a subscription.

Authentication: JWT required

Path Parameters:

Response: 200 OK

Notification Endpoints

16. POST /v1/devicetokens

Description: Registers a device for push notifications.

Request Body:

{
  "userId": "a1b2c3d4-...",
  "deviceToken": "firebase-token-123",
  "os": "iOS"
}

Response: 200 OK

Examples

User Login

curl -X POST "https://api.example.com/v1/users/authenticate" \
  -H "Content-Type: application/json" \
  -d '{"username": "user@example.com", "password": "password123"}'

Get User Details

curl -X GET "https://api.example.com/v1/users/details" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Update Settings

curl -X PATCH "https://api.example.com/v1/users/settings" \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{"timezone": "America/Chicago"}'

Google Sign-In

curl -X POST "https://api.example.com/v1/auth/google" \
  -H "Content-Type: application/json" \
  -d '{"code": "google-oauth-code"}'

Related Endpoints