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#
Authentication#
Register User#
Create a new user account.
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):
{
"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.
POST /login
Content-Type: application/json
{
"email": "user@example.com",
"password": "SecureP@ssw0rd!"
}
Response (200 OK):
{
"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:
{
"success": true,
"data": {
"requiresTwoFactor": true,
"twoFactorToken": "2fa_temp_token_xyz",
"methods": ["totp", "sms"]
}
}
Verify Two-Factor#
Complete login with 2FA code.
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.
POST /refresh-token
Content-Type: application/json
{
"refreshToken": "eyJhbGciOiJSUzI1NiIs..."
}
Response (200 OK):
{
"success": true,
"data": {
"accessToken": "eyJhbGciOiJSUzI1NiIs...",
"refreshToken": "eyJhbGciOiJSUzI1NiIs...",
"expiresIn": 900
}
}
Logout#
Invalidate current session.
POST /logout
Authorization: Bearer <access_token>
Response (204 No Content)
Password Reset Request#
Request password reset email.
POST /password/reset-request
Content-Type: application/json
{
"email": "user@example.com"
}
Response (200 OK):
{
"success": true,
"data": {
"message": "If an account exists, a reset email has been sent."
}
}
Password Reset#
Reset password with token from email.
POST /password/reset
Content-Type: application/json
{
"token": "reset_token_from_email",
"newPassword": "NewSecureP@ssw0rd!"
}
Response (200 OK):
{
"success": true,
"data": {
"message": "Password successfully reset."
}
}
User Profile#
Get Current User Profile#
GET /profile
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
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#
POST /profile/avatar
Authorization: Bearer <access_token>
Content-Type: multipart/form-data
avatar: <binary image data>
Response (200 OK):
{
"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#
GET /users/:username
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
GET /creator
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
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).
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):
{
"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#
GET /settings
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
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#
POST /settings/2fa/enable
Authorization: Bearer <access_token>
Content-Type: application/json
{
"method": "totp"
}
Response (200 OK):
{
"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#
POST /settings/2fa/confirm
Authorization: Bearer <access_token>
Content-Type: application/json
{
"code": "123456"
}
Response (200 OK):
{
"success": true,
"data": {
"enabled": true,
"backupCodes": ["abcd-1234", "efgh-5678", "ijkl-9012"]
}
}
Social Features#
Follow User#
POST /follow
Authorization: Bearer <access_token>
Content-Type: application/json
{
"userId": "usr_xyz789"
}
Response (200 OK):
{
"success": true,
"data": {
"following": true,
"followedAt": "2026-01-18T12:00:00.000Z"
}
}
Unfollow User#
DELETE /follow/:userId
Authorization: Bearer <access_token>
Response (200 OK):
{
"success": true,
"data": {
"following": false
}
}
Get Following List#
GET /following?cursor=<cursor>&limit=20
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
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#
GET /fan-club/:creatorId
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
POST /fan-club/:creatorId/subscribe
Authorization: Bearer <access_token>
Content-Type: application/json
{
"tierId": "tier_1",
"paymentMethodId": "pm_abc123"
}
Response (200 OK):
{
"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)#
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#
GET /subscriptions
Authorization: Bearer <access_token>
Response (200 OK):
{
"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#
POST /subscriptions/:subscriptionId/cancel
Authorization: Bearer <access_token>
Content-Type: application/json
{
"cancelImmediately": false,
"reason": "Too expensive"
}
Response (200 OK):
{
"success": true,
"data": {
"subscriptionId": "sub_xyz789",
"status": "active",
"cancelAtPeriodEnd": true,
"currentPeriodEnd": "2026-02-18T00:00:00.000Z"
}
}
Data Types#
User Object#
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#
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#
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 |