LastSaaS API Reference

Creates a new user account with email and password. If an invitation token is provided, the user is automatically added to the inviting tenant. A personal tenant is always created for the new user. Returns access and refresh tokens plus the user profile and tenant memberships.

{"email":"user@example.com","password":"secureP@ss1","displayName":"Jane Doe","invitationToken":"(optional)"}

{"accessToken":"eyJ...","refreshToken":"eyJ...",
 "user":{"id":"...","email":"user@example.com","displayName":"Jane Doe","emailVerified":false,"isActive":true,"authMethods":[{"provider":"password"}],"createdAt":"...","updatedAt":"..."},
 "memberships":[{"tenantId":"...","tenantName":"Jane's Team","tenantSlug":"janes-team","role":"owner","isRoot":false}]}

Authenticates a user with email and password. Returns JWT access and refresh tokens. Account is locked for 15 minutes after 5 consecutive failed attempts.

{"email":"user@example.com","password":"secureP@ss1"}

{"accessToken":"eyJ...","refreshToken":"eyJ...","user":{...},"memberships":[...]}

Exchanges a valid refresh token for a new access/refresh token pair. The old refresh token is revoked (rotation). Use this when the access token expires.

{"refreshToken":"eyJ..."}

{"accessToken":"eyJ...","refreshToken":"eyJ...","user":{...},"memberships":[...]}

Confirms the user's email address using a token sent via email. The token is single-use and expires after 24 hours.

{"token":"verification-token-from-email"}

{"message":"Email verified successfully"}

Sends a new verification email to the specified address. Rate-limited to one request per 60 seconds per email. Returns a success message regardless of whether the email exists (prevents enumeration).

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

{"message":"If the email exists, a verification link has been sent"}

Sends a password reset email to the specified address. Returns a success message regardless of whether the email exists (prevents enumeration). Only works for accounts with password authentication enabled.

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

{"message":"If the email exists, a password reset link has been sent"}

Resets the user's password using a token from the reset email. All existing refresh tokens are revoked (logs out all sessions). The token is single-use.

{"token":"reset-token-from-email","newPassword":"newSecureP@ss1"}

{"message":"Password reset successfully"}

Redirects the user to Google's OAuth consent screen. After authorization, Google redirects back to the callback URL. Only available when Google OAuth is configured.

Handles the OAuth callback from Google. Links the Google account to an existing user (matched by email) or creates a new account. Redirects to the frontend with tokens in the URL fragment: /auth/callback#access_token=...&refresh_token=...

Returns the authenticated user's profile and all tenant memberships. Use this to hydrate the session after login or page refresh.

{"user":{"id":"...","email":"...","displayName":"...","emailVerified":true,"isActive":true,"authMethods":[...],"createdAt":"...","updatedAt":"...","lastLoginAt":"..."},"memberships":[{"tenantId":"...","tenantName":"...","tenantSlug":"...","role":"owner","isRoot":false}]}

Revokes the current access token. If a refresh token is provided in the body, it is also revoked.

{"refreshToken":"eyJ... (optional)"}

{"message":"Logged out successfully"}

Changes the authenticated user's password. If the user already has a password, the current password must be provided. For Google-only accounts adding a password for the first time, the current password field can be omitted.

{"currentPassword":"oldP@ss (required if password exists)","newPassword":"newSecureP@ss1"}

{"message":"Password changed successfully"}

Accepts a pending invitation to join a tenant. The invitation token comes from the invitation email. The user is added to the tenant with the role specified in the invitation. Returns updated memberships.

{"token":"invitation-token-from-email"}

{"message":"Invitation accepted","memberships":[{"tenantId":"...","tenantName":"...","tenantSlug":"...","role":"user","isRoot":false}]}

Returns all members of the current tenant with their roles and join dates. Any member of the tenant can call this endpoint.

{"members":[{"userId":"...","email":"user@example.com","displayName":"Jane Doe","role":"owner","joinedAt":"2025-01-15T..."}]}

Sends an invitation email to join the tenant. If the email belongs to an existing user, they receive a join link. If not, they receive a signup-and-join link. Invitations expire after 7 days. Only owners can invite admins; admins can only invite users. Subject to the plan's user limit.

{"email":"newuser@example.com","role":"user"}

{"message":"Invitation sent"}

Removes a member from the tenant. You cannot remove the owner or yourself. Admins can only remove regular users (not other admins).

{"message":"Member removed"}

Changes a member's role to admin or user. Only the tenant owner can change roles. To transfer ownership, use the dedicated transfer endpoint instead.

{"role":"admin"}

{"message":"Role updated"}

Transfers ownership of the tenant to another member. The current owner is demoted to admin. The target user must already be a member of the tenant. This action cannot be undone by the previous owner.

{"message":"Ownership transferred"}

Returns all messages for the authenticated user, sorted by creation date (newest first). Messages include system notifications like invitation alerts.

{"messages":[{"id":"...","userId":"...","type":"invitation","title":"...","body":"...","isRead":false,"createdAt":"..."}]}

Returns the number of unread messages for the authenticated user. Use this for notification badges.

{"count":3}

Marks a specific message as read. Only the message owner can mark it as read.

{"message":"Marked as read"}

Returns all subscription plans visible to the current user, along with the tenant's current plan, billing status, credits, and subscription interval. Requires the X-Tenant-ID header to determine the tenant's current state.

{"plans":[{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,"annualDiscountPct":20,"usageCreditsPerMonth":1000,"creditResetPolicy":"reset","bonusCredits":0,"userLimit":10,"entitlements":{...}}],
 "currentPlanId":"...","billingWaived":false,"tenantSubscriptionCredits":500,"tenantPurchasedCredits":0,
 "billingStatus":"active","billingInterval":"year","currentPeriodEnd":"2026-01-15T...","canceledAt":null}

Returns all active credit bundles available for purchase, sorted by sort order.

{"bundles":[{"id":"...","name":"500 Credits","credits":500,"priceCents":4900,"isActive":true,"sortOrder":1}]}

Creates a Stripe Checkout session for a plan subscription or credit bundle purchase. For free plans or billing-waived tenants, the plan is assigned immediately without Stripe. Specify either planId or bundleId, not both.

{"planId":"ObjectID (or bundleId)","billingInterval":"year"}

{"checkoutUrl":"https://checkout.stripe.com/..."}

Creates a Stripe Billing Portal session URL where the customer can manage payment methods, view invoices, and update billing details. The tenant must have an existing Stripe customer ID.

{"portalUrl":"https://billing.stripe.com/..."}

Returns paginated billing transactions for the current tenant, sorted by date (newest first).

{"transactions":[{"id":"...","tenantId":"...","description":"Pro Plan (Annual)","type":"subscription","amountCents":29900,"currency":"usd","invoiceNumber":"INV-0001","createdAt":"..."}],
 "total":15,"page":1,"perPage":20}

Returns the full transaction record and tenant name for rendering an invoice view.

{"transaction":{...},"tenant":{"name":"Acme Corp"}}

Generates and returns a PDF invoice for the specified transaction. The response Content-Type is application/pdf.

Cancels the tenant's current subscription at the end of the billing period. The tenant retains access until the period ends. Returns the period end date.

{"message":"Subscription will cancel at end of billing period","currentPeriodEnd":"2026-02-15T..."}

Returns the Stripe publishable key for initializing Stripe.js on the frontend. Returns an empty string if Stripe is not configured.

{"publishableKey":"pk_live_..."}

Returns the current version and copyright information.

{"version":"1.00","copyright":"..."}

Returns high-level system metrics including total user count, tenant count, and overall health status with any active issues.

{"users":142,"tenants":38,"health":{"healthy":true,"issues":[]}}

Returns paginated system audit logs with optional filtering by severity, user, or text search. Logs record authentication events, configuration changes, billing actions, and other system activity.

{"logs":[{"id":"...","severity":"high","message":"Webhook created: Test → https://...","userId":"...","createdAt":"..."}],"total":256}

Returns all known server nodes and their current status. In a multi-machine deployment, each machine registers as a separate node.

{"nodes":[{"id":"...","hostname":"d892610f630968","region":"iad","lastSeen":"...","isHealthy":true}]}

Returns time-series performance metrics (CPU, memory, request rate, latency) for a specific node or aggregated across all nodes.

{"metrics":[{"timestamp":"...","cpu":23.5,"memoryMB":128,"requestsPerMin":45,"avgLatencyMs":12}],"from":"...","to":"..."}

Returns the latest health snapshot for each active node. Use this for real-time monitoring dashboards.

{"metrics":[{"nodeId":"...","cpu":15.2,"memoryMB":96,"requestsPerMin":30,"avgLatencyMs":8}]}

Checks the connectivity and status of all external integrations: MongoDB, Stripe, Resend (email), and Google OAuth. Returns the check status and last 24h call count for each.

{"integrations":[{"name":"mongodb","status":"healthy","lastCheck":"...","calls24h":1520},{"name":"stripe","status":"healthy",...},{"name":"resend","status":"not_configured",...}]}

Returns all configuration variables as a map keyed by variable name. Includes system variables (read-only name/type) and user-created variables.

{"configs":{"app.name":{"name":"app.name","type":"string","value":"LastSaaS","description":"Application name","isSystem":true,"options":""},...}}

Creates a new user-defined configuration variable. Variable names must be unique. Types: string, numeric, enum (pipe-separated options), template (supports placeholders).

{"name":"feature.max_uploads","description":"Maximum uploads per user","type":"numeric","value":"100","options":""}

{"name":"feature.max_uploads","type":"numeric","value":"100","description":"Maximum uploads per user","isSystem":false,"options":""}

Returns a single configuration variable by name.

{"name":"app.name","type":"string","value":"LastSaaS","description":"Application name","isSystem":true,"options":""}

Updates the value (and optionally description/options) of a configuration variable. System variables only allow value changes. Enum variables validate against the options list.

{"value":"200","description":"Updated description (optional)"}

{"name":"feature.max_uploads","type":"numeric","value":"200",...}

Deletes a user-created configuration variable. System variables cannot be deleted.

{"message":"Config variable deleted"}

Returns all tenants with member counts and billing information. Includes the plan name, billing waived status, and credit balances.

{"tenants":[{"id":"...","name":"Acme Corp","slug":"acme-corp","isRoot":false,"isActive":true,"memberCount":5,"planName":"Pro","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200,"createdAt":"..."}]}

Returns full tenant details including all members with roles and join dates.

{"tenant":{"id":"...","name":"Acme Corp","slug":"acme-corp","isRoot":false,"isActive":true,"planId":"...","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200,"stripeCustomerId":"cus_...","billingStatus":"active","billingInterval":"year","currentPeriodEnd":"...","createdAt":"...","updatedAt":"..."},
 "members":[{"userId":"...","email":"jane@acme.com","displayName":"Jane Doe","role":"owner","joinedAt":"..."}]}

Updates tenant properties. All fields are optional — only provided fields are changed. Can modify name, billing waived status, and credit balances.

{"name":"New Name (optional)","billingWaived":true,"subscriptionCredits":5000,"purchasedCredits":100}

{"message":"Tenant updated"}

Sets a tenant's active status. Deactivated tenants cannot access the application. The root tenant cannot be deactivated.

{"isActive":false}

{"message":"Tenant deactivated"}

Directly assigns a plan to a tenant (bypasses Stripe). Can also toggle billing waived status. Send an empty planId or omit it to remove the plan.

{"planId":"ObjectID (optional)","billingWaived":true}

{"status":"updated"}

Cancels a tenant's Stripe subscription. Set immediate to true to cancel now; otherwise cancels at the end of the billing period.

{"immediate":false}

{"message":"Subscription canceled"}

Manually updates subscription metadata such as the current period end date. Use this for correcting billing records.

{"currentPeriodEnd":"2026-03-15T00:00:00Z"}

{"message":"Subscription updated"}

Returns all users with summary information including tenant count and last login time.

{"users":[{"id":"...","email":"jane@example.com","displayName":"Jane Doe","emailVerified":true,"isActive":true,"tenantCount":2,"createdAt":"...","lastLoginAt":"..."}]}

Returns full user profile including authentication methods and all tenant memberships with billing details for each tenant.

{"user":{"id":"...","email":"jane@example.com","displayName":"Jane Doe","emailVerified":true,"isActive":true,"authMethods":[{"provider":"password"},{"provider":"google"}],"createdAt":"...","lastLoginAt":"..."},
 "memberships":[{"tenantId":"...","tenantName":"Acme Corp","tenantSlug":"acme-corp","isRoot":false,"role":"owner","joinedAt":"...","planId":"...","planName":"Pro","billingWaived":false,"subscriptionCredits":1000,"purchasedCredits":200}]}

Updates a user's email or display name. Both fields are optional — only provided fields are changed.

{"email":"new@example.com","displayName":"New Name"}

{"message":"User updated"}

Sets a user's active status. Deactivated users cannot log in. Active sessions are not immediately terminated but will fail on the next API call.

{"isActive":false}

{"message":"User deactivated"}

Changes a user's role within a specific tenant. Can set to owner, admin, or user. When changing to owner, the current owner is demoted to admin.

{"role":"admin"}

{"message":"Role updated"}

Returns a preview of what would happen if the user were deleted. Shows all tenants where the user is the owner and lists other members who could take ownership. Returns canDelete: false if the user is the sole owner of the root tenant.

{"canDelete":true,"ownerships":[{"tenantId":"...","tenantName":"Acme Corp","isRoot":false,"otherMembers":[{"userId":"...","email":"bob@acme.com","displayName":"Bob","role":"admin","joinedAt":"..."}]}]}

Permanently deletes a user account. For tenants where the user is the owner, specify a replacement owner or confirm tenant deletion. The request body must resolve all ownership conflicts identified by the preflight endpoint.

{"replacementOwners":{"tenantId":"newOwnerUserId"},"confirmTenantDeletions":["tenantId"]}

{"message":"User deleted"}

Returns all subscription plans with subscriber counts.

{"plans":[{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,"annualDiscountPct":20,"usageCreditsPerMonth":1000,"creditResetPolicy":"reset","bonusCredits":0,"userLimit":10,"entitlements":{"feature_x":{"type":"bool","boolValue":true,"description":"..."}},"isSystem":false,"createdAt":"..."}]}

Returns full details for a single plan.

{"id":"...","name":"Pro","description":"...","monthlyPriceCents":2900,...}

Returns all unique entitlement keys currently in use across all plans, with their types and descriptions.

{"keys":[{"key":"feature_x","type":"bool","description":"Enable feature X"}]}

Creates a new subscription plan. Plan names must be unique. Credit reset policy can be reset (credits reset each month) or accrue (unused credits roll over). Set userLimit to 0 for unlimited users.

{"name":"Enterprise","description":"For large teams","monthlyPriceCents":9900,"annualDiscountPct":25,"usageCreditsPerMonth":5000,"creditResetPolicy":"accrue","bonusCredits":1000,"userLimit":0,"entitlements":{"feature_x":{"type":"bool","boolValue":true,"description":"Enable feature X"}}}

{"id":"...","name":"Enterprise",...}

Updates an existing plan. System plans (Free) cannot be renamed. All fields from the create endpoint are accepted.

{"name":"Enterprise Plus","monthlyPriceCents":14900,...}

{"id":"...","name":"Enterprise Plus",...}

Deletes a plan. System plans and plans with active subscribers cannot be deleted. Reassign subscribers first.

{"status":"deleted"}

Returns all credit bundles (active and inactive), sorted by sort order.

{"bundles":[{"id":"...","name":"500 Credits","credits":500,"priceCents":4900,"isActive":true,"sortOrder":1,"createdAt":"..."}]}

Creates a new credit bundle for purchase. Bundle names must be unique. Credits and price must be positive values.

{"name":"1000 Credits","credits":1000,"priceCents":8900,"isActive":true,"sortOrder":2}

{"id":"...","name":"1000 Credits","credits":1000,...}

Updates an existing credit bundle.

{"name":"1000 Credits","credits":1000,"priceCents":7900,...}

{"id":"...","name":"1000 Credits",...}

Permanently deletes a credit bundle.

{"status":"deleted"}

Returns paginated billing transactions across all tenants. Supports filtering by tenant and text search across description, invoice number, plan name, and bundle name.

{"transactions":[{"id":"...","tenantId":"...","description":"Pro Plan (Annual)","type":"subscription","amountCents":29900,"currency":"usd","invoiceNumber":"INV-0001","planName":"Pro","createdAt":"..."}],
 "total":150,"page":1,"perPage":50}

Returns time-series financial data for charting. Supported metrics: revenue (daily revenue), arr (annualized recurring revenue), dau (daily active users), mau (monthly active users).

{"data":[{"date":"2026-02-01","value":15000},{"date":"2026-02-02","value":18500},...]}

Returns all active API keys with metadata. The key hash is never returned — only the preview (last 8 characters) is shown.

{"apiKeys":[{"id":"...","name":"CI/CD Pipeline","keyPreview":"x7k9m2pq","authority":"admin","createdBy":"...","createdAt":"...","lastUsedAt":"...","isActive":true}]}

Creates a new API key and returns the raw key value. The raw key is only returned once — it is stored as a SHA-256 hash and cannot be retrieved later. Authority levels: admin keys auto-resolve the root tenant and get admin-level access; user keys require an X-Tenant-ID header.

{"name":"CI/CD Pipeline","authority":"admin"}

{"apiKey":{"id":"...","name":"CI/CD Pipeline","keyPreview":"x7k9m2pq","authority":"admin",...},"rawKey":"lsk_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmno"}

Soft-deletes an API key. The key immediately stops working for authentication. This cannot be undone.

{"status":"deleted"}

Returns all active webhook configurations sorted by creation date (newest first).

{"webhooks":[{"id":"...","name":"Provisioning","description":"...","url":"https://example.com/webhook","secretPreview":"k9m2pqx7","events":["tenant.created"],"isActive":true,"createdBy":"...","createdAt":"..."}]}

Returns all webhook event types that can be subscribed to, with descriptions.

{"eventTypes":[{"type":"tenant.created","description":"Fired when a new tenant is created..."}]}

Creates a new webhook with an auto-generated signing secret (prefixed whsec_). The full secret is returned in the response — you can also retrieve it later from the detail endpoint. All deliveries include an X-Webhook-Signature header containing the HMAC-SHA256 signature of the payload.

{"name":"Provisioning","description":"Provision new tenants","url":"https://example.com/webhook","events":["tenant.created"]}

{"webhook":{"id":"...","name":"Provisioning",...},"secret":"whsec_ABCDEFGHIJKLMNOPQRSTUVWXYZabcdef"}

Returns full webhook configuration including the signing secret and the 20 most recent delivery attempts with their payloads and response details.

{"webhook":{"id":"...","name":"Provisioning",...},"secret":"whsec_...","deliveries":[{"id":"...","eventType":"tenant.created","payload":"{...}","responseCode":200,"responseBody":"ok","success":true,"durationMs":120,"createdAt":"..."}]}

Updates the webhook's name, description, URL, or subscribed events. The signing secret is not affected.

{"name":"Updated Name","description":"...","url":"https://new-url.com/webhook","events":["tenant.created"]}

{"webhook":{"id":"...","name":"Updated Name",...}}

Soft-deletes a webhook. It immediately stops receiving event deliveries.

{"status":"deleted"}

Delivers a test tenant.created event with sample data to the webhook URL. The delivery includes an X-Webhook-Test: true header so your handler can distinguish test deliveries. Returns the delivery result.

{"delivery":{"id":"...","eventType":"tenant.created","success":true,"responseCode":200,"durationMs":85,"createdAt":"..."}}

Generates a new signing secret for the webhook. The old secret immediately stops working. Returns the new secret and preview.

{"secret":"whsec_NEWsecretABCDEFGHIJKLMNOPQRSTUV","secretPreview":"QRSTUV12"}

Returns the current application version. All API responses also include the version in the X-API-Version response header and a unique X-Request-ID header for tracing.

{"version":"1.00"}

Returns a simple health status. Used by load balancers and monitoring services to verify the server is running.

{"status":"ok"}

Receives and processes Stripe webhook events. Authenticated via Stripe's webhook signature verification — not accessible with API keys or JWT tokens. Handles checkout completion, subscription updates, cancellations, and invoice events.