Account Management

Overview

The AudioPod AI Account Management API provides endpoints for managing user profiles, account settings, and personal information. This API allows you to update user details, manage phone verification, and handle account preferences programmatically.

Key Features

Profile Management: Update name, contact information, and preferences
Phone Verification: Add and verify phone numbers for enhanced security
Account Settings: Manage account type, usage preferences, and onboarding status
Provider Linking: Connect and manage OAuth provider accounts
Account Information: Retrieve current user data and account status

Authentication

All endpoints require authentication:

API Key: Authorization: Bearer your_api_key
JWT Token: Authorization: Bearer your_jwt_token

Get Account Information

Current User Profile

Get detailed information about the authenticated user account.

GET
Python
cURL

GET /api/v1/auth/me
Authorization: Bearer {api_key}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "email": "user@example.com",
  "full_name": "John Doe",
  "is_active": true,
  "is_superuser": false,
  "is_verified": true,
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z",
  "image": "https://api.audiopod.ai/avatars/user_550e8400.jpg",
  "user_type": "individual",
  "audio_usage": "creator",
  "onboarding_completed": true,
  "referral_source": "google_search",
  "phone_number": "+1234567890",
  "country_code": "US",
  "phone_verified": true,
  "credits": {
    "credits_balance": 1500,
    "payg_balance": 750,
    "total_available_credits": 2250,
    "last_reset_at": "2024-01-01T00:00:00Z",
    "total_credits_used": 3250,
    "total_payg_credits_purchased": 750,
    "next_reset_date": "2024-02-01T00:00:00Z",
    "credits_per_month": 2000,
    "credit_multipliers": {
      "default": 5.5,
      "speech_translation": 55,
      "translation": 27.5,
      "voice_cloning": 5.5,
      "voice_conversion": 16.5
    }
  },
  "subscription": {
    "plan_id": "price_1RG2s1CxLzg0ytJK5K3V7hz6",
    "plan_name": "Starter",
    "is_free_plan": false,
    "status": "active",
    "current_period_start": "2024-01-15T10:30:00Z",
    "current_period_end": "2024-02-15T10:30:00Z",
    "cancel_at": null
  },
  "is_eligible_for_first_time_discount": false,
  "first_time_discount_active": false
}

Update Account Information

Update User Profile

Modify user profile information and preferences.

PATCH
Python
cURL

PATCH /api/v1/auth/me
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "full_name": "John Smith",
  "user_type": "company",
  "audio_usage": "business",
  "referral_source": "word_of_mouth",
  "phone_number": "+1987654321",
  "country_code": "US"
}

Available User Types:

individual - Personal use
company - Business use

Available Audio Usage Types:

personal - Personal projects
creator - Content creation
business - Business applications
voice_actor - Professional voice work
education - Educational content
engineer - Technical applications
marketer - Marketing content
other - Other use cases

Phone Verification

Send Phone Verification

Send OTP code to phone number for verification.

POST
Python

POST /api/v1/auth/send-phone-verification
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "phone_number": "+1234567890",
  "country_code": "US"
}

Response:

{
  "message": "Verification code sent successfully",
  "expires_in_minutes": 10
}

Verify Phone Number

Confirm phone number with OTP code.

POST
Python

POST /api/v1/auth/verify-phone
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "phone_number": "+1234567890",
  "otp_code": "123456"
}

Response:

{
  "verified": true,
  "message": "Phone number verified successfully"
}

Password Management

Change Password

Update account password with current password verification.

POST
Python

POST /api/v1/auth/change-password
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "current_password": "current_secure_password",
  "new_password": "new_secure_password_123"
}

Password Requirements:

Minimum 6 characters
At least one letter (uppercase or lowercase)
At least one number

OAuth Provider Management

Link OAuth Provider

Connect external OAuth provider accounts (Google, GitHub).

POST
Python

POST /api/v1/auth/account-providers
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "provider": "google",
  "provider_account_id": "google_user_id_123",
  "type": "oauth",
  "access_token": "google_access_token",
  "refresh_token": "google_refresh_token",
  "expires_at": 1640995200,
  "scope": "email profile"
}

List Connected Providers

Get all connected OAuth provider accounts.

GET
Python

GET /api/v1/auth/account-providers
Authorization: Bearer {api_key}

Unlink OAuth Provider

Remove connection to an OAuth provider.

DELETE
Python

DELETE /api/v1/auth/account-providers/{provider}
Authorization: Bearer {api_key}

Session Management

Get Active Sessions

List all active user sessions across devices.

GET
Python

GET /api/v1/auth/sessions
Authorization: Bearer {api_key}

Response:

[
  {
    "session_id": "sess_abc123def456",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_info": "Chrome 120.0 on macOS",
    "ip_address": "192.168.1.100",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)...",
    "created_at": "2024-01-20T10:30:00Z",
    "last_active": "2024-01-20T14:22:00Z",
    "expires_at": "2024-02-20T10:30:00Z",
    "is_current": true
  },
  {
    "session_id": "sess_def456ghi789",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_info": "Safari 17.0 on iOS",
    "ip_address": "192.168.1.105",
    "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0...)...",
    "created_at": "2024-01-19T08:15:00Z",
    "last_active": "2024-01-19T18:45:00Z",
    "expires_at": "2024-02-19T08:15:00Z",
    "is_current": false
  }
]

Revoke Sessions

Revoke specific sessions or all other sessions.

POST
Python

POST /api/v1/auth/sessions/revoke
Authorization: Bearer {api_key}
Content-Type: application/json

{
  "session_id": "sess_def456ghi789",
  "revoke_all_others": false
}

Update Device Information

Update device information for current session.

POST
Python

POST /api/v1/auth/sessions/update-device-info
Authorization: Bearer {api_key}

Account Validation

Validate Session

Check if current session is valid and get session information.

GET
Python

GET /api/v1/auth/session/validate
Authorization: Bearer {api_key}

Response:

{
  "is_valid": true,
  "session_info": {
    "session_id": "sess_abc123def456",
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "device_info": "Chrome 120.0 on macOS",
    "created_at": "2024-01-20T10:30:00Z",
    "last_active": "2024-01-20T14:22:00Z",
    "expires_at": "2024-02-20T10:30:00Z",
    "is_current": true
  },
  "user": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "email": "user@example.com",
    "full_name": "John Doe",
    "is_verified": true
  },
  "expires_in": 2592000,
  "needs_refresh": false
}

Integration Examples

Account Health Check

class AccountManager:
    def __init__(self, api_key):
        self.api_key = api_key
        self.base_url = "https://api.audiopod.ai/api/v1"
        self.headers = {"Authorization": f"Bearer {api_key}"}
    
    def get_account_health(self):
        """Get comprehensive account status"""
        try:
            # Validate session
            session_response = requests.get(
                f"{self.base_url}/auth/session/validate",
                headers=self.headers
            )
            
            if session_response.status_code != 200:
                return {"status": "invalid_session", "healthy": False}
            
            session_data = session_response.json()
            
            # Get user profile
            profile_response = requests.get(
                f"{self.base_url}/auth/me",
                headers=self.headers
            )
            
            if profile_response.status_code != 200:
                return {"status": "profile_error", "healthy": False}
            
            user_data = profile_response.json()
            
            # Check account completeness
            completeness_score = self._calculate_completeness(user_data)
            
            # Check credit balance
            credits = user_data.get('credits', {})
            low_credits = credits.get('total_available_credits', 0) < 100
            
            return {
                "status": "healthy",
                "healthy": True,
                "session_valid": session_data["is_valid"],
                "needs_refresh": session_data.get("needs_refresh", False),
                "account_verified": user_data["is_verified"],
                "phone_verified": user_data.get("phone_verified", False),
                "onboarding_complete": user_data.get("onboarding_completed", False),
                "completeness_score": completeness_score,
                "low_credits_warning": low_credits,
                "credits_available": credits.get('total_available_credits', 0)
            }
        
        except Exception as e:
            return {"status": "error", "healthy": False, "error": str(e)}
    
    def _calculate_completeness(self, user_data):
        """Calculate profile completeness score"""
        fields_to_check = [
            'full_name', 'user_type', 'audio_usage', 
            'phone_number', 'phone_verified'
        ]
        
        completed_fields = 0
        for field in fields_to_check:
            if field in user_data and user_data[field]:
                completed_fields += 1
        
        return (completed_fields / len(fields_to_check)) * 100
    
    def ensure_phone_verified(self, phone_number, country_code="US"):
        """Ensure phone number is verified"""
        try:
            # Send verification code
            verify_response = requests.post(
                f"{self.base_url}/auth/send-phone-verification",
                headers=self.headers,
                json={
                    "phone_number": phone_number,
                    "country_code": country_code
                }
            )
            
            if verify_response.status_code == 200:
                return {
                    "verification_sent": True,
                    "message": "Verification code sent to phone"
                }
            else:
                return {
                    "verification_sent": False,
                    "error": verify_response.json()
                }
        
        except Exception as e:
            return {"verification_sent": False, "error": str(e)}

# Usage example
account_manager = AccountManager("your_api_key")
health_status = account_manager.get_account_health()

if health_status["healthy"]:
    print("Account is healthy")
    if health_status["low_credits_warning"]:
        print("Warning: Low credit balance")
    if not health_status["phone_verified"]:
        print("Consider verifying phone number for enhanced security")
else:
    print(f"Account issue: {health_status['status']}")

Error Handling

400 Bad Request - Invalid Phone Number

Causes: - Invalid phone number format - Unsupported country code Solutions: - Use international format (+1234567890) - Check supported country codes - Verify phone number is valid

401 Unauthorized - Invalid Session

Causes: - Token expired - Invalid API key - Session revoked Solutions: - Refresh access token - Check API key is correct - Re-authenticate if session expired

409 Conflict - Provider Already Linked

Causes: - OAuth provider already connected - Email conflict with existing account Solutions: - Unlink existing provider first - Use different email address

422 Validation Error

Causes: - Invalid user type - Password doesn’t meet requirements - Invalid field values Solutions: - Check allowed values for enums - Verify password requirements - Validate input data format

Best Practices

Security Recommendations

# Secure account management practices
security_checklist = {
    "password_policy": {
        "min_length": 8,
        "require_uppercase": True,
        "require_lowercase": True,
        "require_numbers": True,
        "require_special_chars": True,
        "change_frequency": "every_6_months"
    },
    "session_management": {
        "review_sessions_regularly": True,
        "revoke_unused_sessions": True,
        "monitor_login_locations": True,
        "enable_notifications": True
    },
    "phone_verification": {
        "verify_phone_number": True,
        "use_for_2fa": True,
        "keep_updated": True
    },
    "oauth_providers": {
        "link_trusted_providers": True,
        "review_permissions": True,
        "unlink_unused_providers": True
    }
}

Profile Completion

def ensure_complete_profile(api_key):
    """Ensure user profile is complete for best experience"""
    
    account_manager = AccountManager(api_key)
    
    # Get current profile
    profile_response = requests.get(
        "https://api.audiopod.ai/api/v1/auth/me",
        headers={"Authorization": f"Bearer {api_key}"}
    )
    
    user_data = profile_response.json()
    
    # Check missing fields
    recommendations = []
    
    if not user_data.get('user_type'):
        recommendations.append("Set account type (individual/company)")
    
    if not user_data.get('audio_usage'):
        recommendations.append("Specify primary audio usage")
    
    if not user_data.get('phone_verified'):
        recommendations.append("Verify phone number for security")
    
    if not user_data.get('full_name'):
        recommendations.append("Add full name to profile")
    
    return {
        "complete": len(recommendations) == 0,
        "recommendations": recommendations,
        "completeness_score": account_manager._calculate_completeness(user_data)
    }

Authentication & Account

Voice

Music

Speech

Utilities

Overview

Key Features

Authentication

Get Account Information

Current User Profile

Update Account Information

Update User Profile

Phone Verification

Send Phone Verification

Verify Phone Number

Password Management

Change Password

OAuth Provider Management

Link OAuth Provider

List Connected Providers

Unlink OAuth Provider

Session Management

Get Active Sessions

Revoke Sessions

Update Device Information

Account Validation

Validate Session

Integration Examples

Account Health Check

Error Handling

Best Practices

Security Recommendations

Profile Completion

Next Steps

API Keys

Account Registration

Authentication & Account

Voice

Music

Speech

Utilities

​Overview

​Key Features

​Authentication

​Get Account Information

​Current User Profile

​Update Account Information

​Update User Profile

​Phone Verification

​Send Phone Verification

​Verify Phone Number

​Password Management

​Change Password

​OAuth Provider Management

​Link OAuth Provider

​List Connected Providers

​Unlink OAuth Provider

​Session Management

​Get Active Sessions

​Revoke Sessions

​Update Device Information

​Account Validation

​Validate Session

​Integration Examples

​Account Health Check

​Error Handling

​Best Practices

​Security Recommendations

​Profile Completion

​Next Steps

API Keys

Account Registration

Overview

Key Features

Authentication

Get Account Information

Current User Profile

Update Account Information

Update User Profile

Phone Verification

Send Phone Verification

Verify Phone Number

Password Management

Change Password

OAuth Provider Management

Link OAuth Provider

List Connected Providers

Unlink OAuth Provider

Session Management

Get Active Sessions

Revoke Sessions

Update Device Information

Account Validation

Validate Session

Integration Examples

Account Health Check

Error Handling

Best Practices

Security Recommendations

Profile Completion

Next Steps