Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vchata.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication Controller

The Authentication Controller provides secure user registration, login, profile management, and session handling for the VChata platform.

​
Base Path

/auth

​
Endpoints

​
Sign Up

POST /auth/signup
Content-Type: application/json

{
  "email": "john.doe@example.com",
  "password": "SecurePassword123!",
  "firstName": "John",
  "lastName": "Doe",
  "organizationName": "Acme Corp",
  "timezone": "America/New_York",
  "paymentMethodId": "pm_1234567890"
}

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "authProvider": "LOCAL",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "organization": {
    "id": "org_xyz789",
    "name": "Acme Corp",
    "createdAt": "2024-01-15T10:00:00Z"
  },
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "User and organization created successfully"
}
Description: Creates a new user account along with an organization. This endpoint:
  • Validates email uniqueness across the platform
  • Creates user with encrypted password
  • Automatically creates an organization
  • Creates Stripe customer and attaches payment method
  • Assigns the user as organization admin
  • Sets long-lived auth token (7 days) as secure httpOnly cookie
Payment Required: A valid payment method ID from PaymentElement is required for account activation.
​
body
object

​
Login

POST /auth/login
Content-Type: application/json

{
  "email": "john.doe@example.com",
  "password": "SecurePassword123!"
}

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "john.doe@example.com",
    "firstName": "John",
    "lastName": "Doe",
    "authProvider": "LOCAL",
    "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=john.doe"
  },
  "organizations": [
    {
      "id": "org_xyz789",
      "name": "Acme Corp",
      "role": "ADMIN",
      "joinedAt": "2024-01-15T10:00:00Z"
    }
  ],
  "authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "message": "Login successful"
}
Description: Authenticates a user with email and password using secure cookie-based authentication. Cookie-Based Authentication:
  • Auth Token: Valid for 7 days, stored in secure httpOnly cookie
  • Cookie is automatically sent with all requests
  • No Authorization headers needed - cookies handle authentication
  • No refresh needed - long-lived token eliminates complexity
​
body
object

​
Get Current User

GET /auth/me
Authorization: Bearer <token>

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "john.doe@example.com",
    "authProvider": "LOCAL",
    "firstName": "John",
    "lastName": "Doe",
    "avatar": "https://api.dicebear.com/7.x/avataaars/svg?seed=john.doe",
    "createdAt": "2024-01-15T10:00:00Z",
    "organizations": [
      {
        "id": "org_xyz789",
        "name": "Acme Corp",
        "role": "ADMIN",
        "joinedAt": "2024-01-15T10:00:00Z"
      },
      {
        "id": "org_def456",
        "name": "Beta Inc",
        "role": "MEMBER",
        "joinedAt": "2024-02-01T14:30:00Z"
      }
    ],
    "currentOrganization": {
      "id": "org_xyz789",
      "name": "Acme Corp",
      "role": "ADMIN"
    }
  },
  "message": "User retrieved successfully"
}
Description: Retrieves the currently authenticated user’s profile along with their organization memberships. Response includes:
  • User profile information
  • All organization memberships with roles
  • Current active organization context
  • Platform permissions and settings

​
Update User Profile

PATCH /auth/me
Authorization: Bearer <token>
Content-Type: application/json

{
  "firstName": "Jane",
  "lastName": "Smith",
  "nickname": "JSmith"
}

{
  "success": true,
  "user": {
    "id": "usr_abc123",
    "email": "jane.smith@example.com",
    "firstName": "Jane",
    "lastName": "Smith",
    "nickname": "JSmith",
    "updatedAt": "2024-01-20T15:30:00Z"
  },
  "message": "Profile updated successfully"
}
Description: Updates the current user’s profile information including first name, last name, nickname, and email.
Important: Email updates will require re-verification (not implemented in this endpoint). All fields are optional - only provided fields will be updated.
​
body
object

​
Logout

POST /auth/logout
Authorization: Bearer <token>

{
  "success": true,
  "message": "Logout successful"
}
Description: Logs out the current user by clearing the authentication cookie and invalidating the session.

​
Create Setup Intent

POST /auth/setup-intent
Authorization: Bearer <token>
Content-Type: application/json

{}

{
  "success": true,
  "clientSecret": "seti_1234567890_secret_abcdef...",
  "message": "Setup intent created successfully"
}
Description: Creates a Stripe setup intent for adding or updating payment methods. This is used to securely collect payment method information without processing a charge.

​
Get User Consents

GET /auth/me/consents
Authorization: Bearer <token>

{
  "success": true,
  "consents": [
    {
      "id": "consent_123",
      "type": "TERMS_OF_SERVICE",
      "version": "1.0",
      "acceptedAt": "2024-01-15T10:00:00Z",
      "ipAddress": "192.168.1.1",
      "userAgent": "Mozilla/5.0..."
    }
  ],
  "message": "Consents retrieved successfully"
}
Description: Retrieves all active consent records for the authenticated user.

​
Iframe Debug

GET /auth/iframe-debug

{
  "isIframe": true,
  "requestInfo": {
    "referer": "https://fcupwvbjh0do6t4stcdo.apps.whop.com/login",
    "userAgent": "Mozilla/5.0...",
    "origin": "https://fcupwvbjh0do6t4stcdo.apps.whop.com",
    "frameContext": null,
    "host": "api.vchata.com",
    "allHeaders": ["authorization", "content-type", "user-agent", ...]
  },
  "cookieConfig": {
    "httpOnly": true,
    "secure": true,
    "sameSite": "none",
    "domain": undefined,
    "path": "/",
    "maxAge": 604800000
  },
  "recommendations": [
    "✅ Cookie will work in iframe context",
    "✅ SameSite=None allows cross-origin usage",
    "✅ Secure flag is properly set"
  ],
  "timestamp": "2024-01-15T10:00:00Z",
  "environment": "production"
}
Description: Debug endpoint to test iframe authentication behavior and cookie settings. Returns information about the request context and cookie configuration. Use this endpoint to:
  • Test iframe detection logic
  • Verify cookie settings for different contexts
  • Debug authentication issues in iframe environments
  • Check CORS and header handling

​
Error Responses

​
Common Errors

{
  "success": false,
  "statusCode": 400,
  "message": [
    "password must be at least 8 characters",
    "email must be an email",
    "paymentMethodId must be a string"
  ],
  "error": "Bad Request"
}

{
  "success": false,
  "statusCode": 401,
  "message": "Invalid email or password",
  "error": "Unauthorized"
}

{
  "success": false,
  "statusCode": 409,
  "message": "User with this email already exists",
  "error": "Conflict"
}

{
  "success": false,
  "statusCode": 502,
  "message": "Payment service temporarily unavailable",
  "error": "Bad Gateway"
}

​
Security Features

  • Secure Cookies: Authentication tokens are stored in httpOnly, secure cookies
  • CSRF Protection: Cookie-based authentication provides built-in CSRF protection
  • Password Encryption: All passwords are hashed using bcrypt
  • Rate Limiting: Login attempts are rate limited to prevent brute force attacks
  • JWT Tokens: Secure JWT tokens with 7-day expiration
  • Iframe Support: Special handling for iframe contexts with fallback mechanisms

​
Authentication Flow

1

User Registration

User provides email, password, and payment method
2

Account Creation

System creates user account, organization, and Stripe customer
3

Token Generation

JWT token is generated and set as secure cookie
4

Login

User can login with email/password to receive auth token
5

API Access

All subsequent requests use the auth token for authentication