Eve library

User Service API

Guide

Revision 1

On this page

REST API documentation for the Aphrodite User Service.

Base URL: https://api.aphrodite.example.com/api/v1 Port: 3000 Authentication: JWT Bearer Token (unless noted)


Table of Contents#

  1. Authentication
  2. User Profile
  3. Creator Profile
  4. Settings
  5. Social Features
  6. Fan Clubs
  7. Subscriptions

Authentication#

Register User#

Create a new user account.

http
POST /register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd!",
  "username": "johndoe",
  "displayName": "John Doe",
  "dateOfBirth": "1990-05-15",
  "acceptedTerms": true,
  "acceptedPrivacy": true
}

Response (201 Created):

json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "username": "johndoe",
      "displayName": "John Doe",
      "verified": false,
      "createdAt": "2026-01-18T12:00:00.000Z"
    },
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900
  }
}

Validation Rules:

Field Rules
email Valid email format, unique
password Min 8 chars, 1 uppercase, 1 lowercase, 1 number
username 3-30 chars, alphanumeric + underscore, unique
displayName 2-50 chars
dateOfBirth Must be 18+ years old
acceptedTerms Must be true

Error Responses:

Code Error Description
400 INVALID_EMAIL Invalid email format
400 WEAK_PASSWORD Password doesn't meet criteria
400 UNDERAGE User is under 18
409 EMAIL_EXISTS Email already registered
409 USERNAME_EXISTS Username already taken

Login#

Authenticate with email and password.

http
POST /login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "SecureP@ssw0rd!"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "user": {
      "id": "usr_abc123",
      "email": "user@example.com",
      "username": "johndoe",
      "displayName": "John Doe",
      "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123.jpg",
      "verified": true,
      "isCreator": false,
      "createdAt": "2026-01-18T12:00:00.000Z"
    },
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900,
    "requiresTwoFactor": false
  }
}

Two-Factor Authentication Required:

json
{
  "success": true,
  "data": {
    "requiresTwoFactor": true,
    "twoFactorToken": "2fa_temp_token_xyz",
    "methods": ["totp", "sms"]
  }
}

Verify Two-Factor#

Complete login with 2FA code.

http
POST /login/verify-2fa
Content-Type: application/json

{
  "twoFactorToken": "2fa_temp_token_xyz",
  "code": "123456",
  "method": "totp"
}

Response (200 OK): Same as login response.


Refresh Token#

Obtain new access token using refresh token.

http
POST /refresh-token
Content-Type: application/json

{
  "refreshToken": "eyJhbGciOiJSUzI1NiIs..."
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "accessToken": "eyJhbGciOiJSUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJSUzI1NiIs...",
    "expiresIn": 900
  }
}

Logout#

Invalidate current session.

http
POST /logout
Authorization: Bearer <access_token>

Response (204 No Content)


Password Reset Request#

Request password reset email.

http
POST /password/reset-request
Content-Type: application/json

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

Response (200 OK):

json
{
  "success": true,
  "data": {
    "message": "If an account exists, a reset email has been sent."
  }
}

Password Reset#

Reset password with token from email.

http
POST /password/reset
Content-Type: application/json

{
  "token": "reset_token_from_email",
  "newPassword": "NewSecureP@ssw0rd!"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "message": "Password successfully reset."
  }
}

User Profile#

Get Current User Profile#

http
GET /profile
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "username": "johndoe",
    "displayName": "John Doe",
    "bio": "Streaming enthusiast",
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123.jpg",
    "bannerUrl": "https://cdn.aphrodite.example.com/banners/usr_abc123.jpg",
    "verified": true,
    "isCreator": false,
    "stats": {
      "following": 42,
      "followers": 0
    },
    "preferences": {
      "language": "en",
      "timezone": "America/New_York",
      "currency": "USD"
    },
    "createdAt": "2026-01-18T12:00:00.000Z",
    "updatedAt": "2026-01-18T14:30:00.000Z"
  }
}

Update User Profile#

http
PUT /profile
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "displayName": "John D.",
  "bio": "Updated bio text",
  "preferences": {
    "language": "es",
    "timezone": "Europe/Madrid"
  }
}

Response (200 OK): Updated profile object.


Update Avatar#

http
POST /profile/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data

avatar: <binary image data>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_abc123_v2.jpg"
  }
}

Constraints:

  • Max file size: 5MB
  • Allowed formats: JPEG, PNG, WebP
  • Minimum dimensions: 200x200
  • Maximum dimensions: 2000x2000

Get User by Username#

http
GET /users/:username
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "id": "usr_xyz789",
    "username": "janedoe",
    "displayName": "Jane Doe",
    "bio": "Content creator",
    "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg",
    "verified": true,
    "isCreator": true,
    "isLive": true,
    "stats": {
      "followers": 15000
    },
    "relationship": {
      "isFollowing": true,
      "isSubscribed": false,
      "subscriptionTier": null
    }
  }
}

Creator Profile#

Get Creator Profile#

http
GET /creator
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "id": "crt_abc123",
    "userId": "usr_abc123",
    "displayName": "Jane Doe",
    "bio": "Professional content creator",
    "category": "entertainment",
    "tags": ["gaming", "music"],
    "schedule": {
      "timezone": "America/Los_Angeles",
      "slots": [
        { "day": "monday", "startTime": "20:00", "endTime": "23:00" },
        { "day": "friday", "startTime": "21:00", "endTime": "01:00" }
      ]
    },
    "tipping": {
      "enabled": true,
      "minimumTip": 1,
      "goals": [
        { "id": "goal_1", "name": "New Camera", "target": 500, "current": 234 }
      ]
    },
    "devices": [
      { "id": "dev_1", "type": "lovense", "name": "Lush 3", "connected": true }
    ],
    "socials": {
      "twitter": "@janedoe",
      "instagram": "@janedoe"
    },
    "stats": {
      "followers": 15000,
      "subscribers": 234,
      "totalStreams": 150,
      "totalHours": 450
    },
    "verificationStatus": "verified",
    "payoutEnabled": true
  }
}

Update Creator Profile#

http
PUT /creator
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "bio": "Updated creator bio",
  "category": "entertainment",
  "tags": ["gaming", "music", "chat"],
  "schedule": {
    "timezone": "America/Los_Angeles",
    "slots": [
      { "day": "monday", "startTime": "20:00", "endTime": "23:00" }
    ]
  },
  "tipping": {
    "enabled": true,
    "minimumTip": 5
  },
  "socials": {
    "twitter": "@janedoe"
  }
}

Response (200 OK): Updated creator profile object.


Become a Creator#

Apply to become a creator (requires identity verification).

http
POST /creator/apply
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "legalName": "Jane Marie Doe",
  "dateOfBirth": "1995-03-20",
  "country": "US",
  "idType": "passport",
  "acceptedCreatorTerms": true
}

Response (202 Accepted):

json
{
  "success": true,
  "data": {
    "applicationId": "app_xyz123",
    "status": "pending_verification",
    "nextStep": "upload_documents",
    "uploadUrl": "https://api.aphrodite.example.com/creator/verify/upload"
  }
}

Settings#

Get User Settings#

http
GET /settings
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "notifications": {
      "email": {
        "marketing": false,
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      },
      "push": {
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      },
      "inApp": {
        "newFollower": true,
        "streamReminders": true,
        "tips": true,
        "messages": true
      }
    },
    "privacy": {
      "showOnlineStatus": true,
      "allowDirectMessages": "followers",
      "showActivity": true,
      "profileVisibility": "public"
    },
    "security": {
      "twoFactorEnabled": true,
      "twoFactorMethod": "totp",
      "loginNotifications": true,
      "trustedDevices": [
        {
          "id": "dev_1",
          "name": "Chrome on MacOS",
          "lastUsed": "2026-01-18T12:00:00.000Z"
        }
      ]
    },
    "streaming": {
      "autoRecord": true,
      "defaultQuality": "1080p",
      "lowLatencyMode": true
    },
    "payment": {
      "defaultCurrency": "USD",
      "autoRecharge": false,
      "autoRechargeAmount": 50
    }
  }
}

Update Settings#

http
PUT /settings
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "notifications": {
    "email": {
      "marketing": true
    }
  },
  "privacy": {
    "showOnlineStatus": false
  }
}

Response (200 OK): Updated settings object.


Enable Two-Factor Authentication#

http
POST /settings/2fa/enable
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "method": "totp"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "secret": "JBSWY3DPEHPK3PXP",
    "qrCodeUrl": "otpauth://totp/Aphrodite:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=Aphrodite",
    "qrCodeImage": "data:image/png;base64,..."
  }
}

Confirm Two-Factor Authentication#

http
POST /settings/2fa/confirm
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "code": "123456"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "enabled": true,
    "backupCodes": ["abcd-1234", "efgh-5678", "ijkl-9012"]
  }
}

Social Features#

Follow User#

http
POST /follow
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "userId": "usr_xyz789"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "following": true,
    "followedAt": "2026-01-18T12:00:00.000Z"
  }
}

Unfollow User#

http
DELETE /follow/:userId
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "following": false
  }
}

Get Following List#

http
GET /following?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": [
    {
      "user": {
        "id": "usr_xyz789",
        "username": "janedoe",
        "displayName": "Jane Doe",
        "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg",
        "isLive": true
      },
      "followedAt": "2026-01-18T12:00:00.000Z"
    }
  ],
  "pagination": {
    "cursor": "next_cursor",
    "hasMore": true,
    "total": 42
  }
}

Get Followers List#

http
GET /followers?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>

Response (200 OK): Same structure as following list.


Fan Clubs#

Get Creator's Fan Club#

http
GET /fan-club/:creatorId
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": {
    "id": "fc_abc123",
    "creatorId": "usr_xyz789",
    "name": "Jane's VIP Club",
    "description": "Exclusive content and perks for subscribers",
    "tiers": [
      {
        "id": "tier_1",
        "name": "Bronze",
        "price": 9.99,
        "currency": "USD",
        "billingPeriod": "monthly",
        "benefits": ["Ad-free viewing", "Custom badge", "Exclusive emotes"]
      },
      {
        "id": "tier_2",
        "name": "Gold",
        "price": 24.99,
        "currency": "USD",
        "billingPeriod": "monthly",
        "benefits": [
          "All Bronze benefits",
          "Priority chat",
          "Monthly exclusive content",
          "Discord access"
        ]
      }
    ],
    "memberCount": 234,
    "userSubscription": null
  }
}

Subscribe to Fan Club#

http
POST /fan-club/:creatorId/subscribe
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "tierId": "tier_1",
  "paymentMethodId": "pm_abc123"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "subscriptionId": "sub_xyz789",
    "tierId": "tier_1",
    "tierName": "Bronze",
    "status": "active",
    "currentPeriodStart": "2026-01-18T00:00:00.000Z",
    "currentPeriodEnd": "2026-02-18T00:00:00.000Z",
    "cancelAtPeriodEnd": false
  }
}

Manage Fan Club (Creator)#

http
POST /fan-club
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "name": "Jane's VIP Club",
  "description": "Exclusive content and perks",
  "tiers": [
    {
      "name": "Bronze",
      "price": 9.99,
      "currency": "USD",
      "billingPeriod": "monthly",
      "benefits": ["Ad-free viewing", "Custom badge"]
    }
  ]
}

Response (201 Created): Created fan club object.


Subscriptions#

Get User Subscriptions#

http
GET /subscriptions
Authorization: Bearer <access_token>

Response (200 OK):

json
{
  "success": true,
  "data": [
    {
      "id": "sub_xyz789",
      "creator": {
        "id": "usr_xyz789",
        "username": "janedoe",
        "displayName": "Jane Doe",
        "avatarUrl": "https://cdn.aphrodite.example.com/avatars/usr_xyz789.jpg"
      },
      "tier": {
        "id": "tier_1",
        "name": "Bronze",
        "price": 9.99
      },
      "status": "active",
      "currentPeriodEnd": "2026-02-18T00:00:00.000Z",
      "cancelAtPeriodEnd": false
    }
  ]
}

Cancel Subscription#

http
POST /subscriptions/:subscriptionId/cancel
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "cancelImmediately": false,
  "reason": "Too expensive"
}

Response (200 OK):

json
{
  "success": true,
  "data": {
    "subscriptionId": "sub_xyz789",
    "status": "active",
    "cancelAtPeriodEnd": true,
    "currentPeriodEnd": "2026-02-18T00:00:00.000Z"
  }
}

Data Types#

User Object#

typescript
interface User {
  id: string;
  email: string;
  username: string;
  displayName: string;
  bio?: string;
  avatarUrl?: string;
  bannerUrl?: string;
  verified: boolean;
  isCreator: boolean;
  createdAt: string;
  updatedAt: string;
}

Creator Object#

typescript
interface Creator {
  id: string;
  userId: string;
  displayName: string;
  bio?: string;
  category: string;
  tags: string[];
  schedule?: Schedule;
  tipping: TippingConfig;
  devices: Device[];
  socials: Record<string, string>;
  stats: CreatorStats;
  verificationStatus: 'pending' | 'verified' | 'rejected';
  payoutEnabled: boolean;
}

Subscription Object#

typescript
interface Subscription {
  id: string;
  creatorId: string;
  userId: string;
  tierId: string;
  status: 'active' | 'canceled' | 'past_due' | 'paused';
  currentPeriodStart: string;
  currentPeriodEnd: string;
  cancelAtPeriodEnd: boolean;
  createdAt: string;
}

Document History#

Date Version Changes
2026-01-18 1.0.0 Initial User Service API docs