Platform Settings

Every SaaS product needs a control plane. The Settings page is yours. It exposes 150+ configurable settings across 11 categories that control authentication, billing, email delivery, storage, styling, and infrastructure — all from the admin panel, without touching code or redeploying.

When you change a setting here, the platform picks it up immediately. No .env file edits, no SSH, no deploys. This is how you iterate on your product in production.

API Endpoints

GET   /api/admin/settings          # Retrieve all settings, grouped by category
PATCH /api/admin/settings          # Partial update — only send the keys you want to change

The GET endpoint returns all settings grouped by category. The PATCH endpoint accepts a partial update — only the keys included in the request body are changed. You do not need to send the full settings object.

Secret Key Handling

Public settings (app name, colors, feature toggles) are returned as-is. Secret settings (API keys, passwords, tokens) are returned as a boolean is_set value indicating whether the key has been configured, without ever exposing the actual value. This means your admin panel UI can show a green checkmark for "Stripe secret configured" without leaking the key itself.

{
    "app.name": "MyApp",
    "mail.smtp_password": { "is_set": true },
    "billing.stripe_secret": { "is_set": false }
}

Setting Categories

App Settings

Your brand identity. Change these values and every email header, page title, notification, and public-facing page updates automatically across the entire platform.

• app_name — The name of your SaaS product. Appears in email subjects, page titles, the navigation bar, and transactional emails. Change it once, it propagates everywhere.
• app_logo_url — URL to your logo image. Used in the nav bar, emails, login page, and invoices. Upload to your storage bucket and paste the URL here.
• support_email — The email address shown in error messages, footers, and "Contact Support" links. When a customer has a problem, this is where they write.
• primary_color — Your brand color (hex value). Applied to buttons, links, active states, and email accent colors. Set it to match your brand guidelines.

Auth Settings

Control how users log in and sign up. The power here is flexibility: launch with email and password only, then add OAuth providers later without a deploy. Close registration when you want to go invite-only. Enforce MFA when an enterprise customer requires it.

• password_login — Enable or disable traditional email + password login. You might disable this after setting up SSO, so all users authenticate through your identity provider instead.
• magic_link — Enable or disable passwordless login via email magic links. Great for reducing friction during onboarding — users click a link instead of creating a password.
• registration — Open or close public registration. Close it when you want to run an invite-only beta, or when you are selling to enterprises that onboard through a sales process.
• mfa — Enable or disable multi-factor authentication globally. When enabled, users are prompted to set up TOTP (authenticator app) on their next login. Essential for compliance-sensitive customers.
• OAuth providers — Each provider (Google, GitHub, Microsoft, Apple) has three settings:
  • enabled — Toggle the provider on or off. Disabled providers do not appear on the login page.
  • client_id — The OAuth application ID from the provider's developer console.
  • client_secret — The OAuth application secret. Stored encrypted, returned as is_set in the API.

  Typical progression: launch with Google OAuth for consumer apps, add GitHub for developer tools, add Microsoft and Apple when enterprise customers ask for them.

SSO Settings

Enterprise customers will ask for SAML SSO. It is usually the first checkbox on their security questionnaire. These settings let you support it without custom code for each customer.

• sso.mode — Three options:
  • disabled — No SSO. Default for early-stage products.
  • per_org — Each organization can configure their own SAML identity provider. This is the most common setup: your enterprise customer provides their IdP metadata, and their team members authenticate through it. Other organizations continue using normal login.
  • global — A single IdP for the entire platform. Use this if you are building an internal tool where everyone authenticates through your company's Okta or Azure AD.
• Global IdP configuration (only used when sso.mode is global):
  • entity_id — The IdP's entity ID (e.g., https://idp.example.com/saml2).
  • sso_url — The IdP's Single Sign-On URL where SAML requests are sent.
  • slo_url — The IdP's Single Logout URL for federated logout.
  • x509_certificate — The IdP's public certificate for validating SAML responses.
  • name_id_format — How the IdP identifies users (usually emailAddress or persistent).

You do not need to fill these in manually. Use the Parse SAML Metadata endpoint (below) to extract them automatically from your customer's metadata URL.

Billing Settings

Your payment infrastructure. Start with Stripe because it has the best developer experience, then add regional gateways as you expand. Switch between live and test mode instantly — no code changes needed.

• billing.driver — The active payment gateway. Options:
  • stripe — Best for US/EU markets. Supports subscriptions, usage billing, invoices, and the Stripe billing portal.
  • paddle — Merchant of record, handles VAT/sales tax for you. Good for solo founders who do not want to deal with tax compliance.
  • mercadopago — The dominant payment gateway in Latin America. Add this when you want to accept Pix, Boleto, and local credit cards in Brazil, Argentina, and Mexico.
  • lemonsqueezy — Another merchant of record option with simple pricing. Good for indie products.
  • paypal — Broad international reach. Some customers in certain regions only have PayPal.
• billing.mode — live or test. In test mode, all charges go through the gateway's sandbox. Use test mode while building your pricing page, switch to live when you are ready to charge real money.
• Per-gateway credentials — Each gateway has its own set of keys:
  • key — Public/publishable key (used by the frontend checkout).
  • secret — Secret key (used by the backend for API calls). Stored encrypted.
  • webhook_secret — Used to verify incoming webhook payloads from the gateway. Critical for security — without this, anyone could fake a "payment succeeded" webhook.

Mail Settings

Every SaaS sends transactional emails: verification, password reset, invoices, team invitations. These settings control how those emails are delivered. Start with SMTP (your existing email provider), then move to a dedicated service when you need better deliverability, open-rate tracking, or higher volume.

• mail.driver — The delivery method:
  • smtp — Works with any email provider (Gmail, Outlook, your hosting provider). Good for getting started, but deliverability can be unreliable at scale.
  • mailgun — Reliable transactional email with good deliverability. Affordable pricing based on volume.
  • postmark — Focused exclusively on transactional email with industry-leading deliverability rates. Best choice when emails absolutely must arrive (password resets, security alerts).
  • resend — Modern email API with a great developer experience. Good React email template support.
  • ses — Amazon SES. Cheapest option at scale (fractions of a cent per email). Requires more setup but unbeatable on cost for high-volume senders.
• from_address — The "From" email address on all outgoing emails (e.g., hello@yourapp.com). Use a domain you own and have configured SPF/DKIM for.
• from_name — The "From" name (e.g., "MyApp" or "MyApp Team"). This is what shows up in the recipient's inbox.
• Per-driver credentials — Each driver has its own fields (API keys, SMTP host/port/username/password, region, etc.). Only the credentials for the active driver are used.

Storage Settings

Controls where uploaded files (avatars, attachments, exports) are stored. Start with local storage for development, then move to S3 or R2 for production so files are served from a CDN and survive server rebuilds.

• storage.driver — Options:
  • local — Files stored on the server's disk. Fine for development and single-server setups, but files are lost if you rebuild the server.
  • s3 — Amazon S3. The standard for production file storage. Files are durable, scalable, and can be served through CloudFront CDN.
  • r2 — Cloudflare R2. S3-compatible but with zero egress fees. If your users download a lot of files, R2 can save significant money compared to S3.
• S3/R2 credentials:
  • bucket — The bucket name where files are stored.
  • region — AWS region (e.g., us-east-1). For R2, use auto.
  • key — Access key ID.
  • secret — Secret access key. Stored encrypted.
  • endpoint — Custom endpoint URL. Required for R2, optional for S3 (use for S3-compatible providers like MinIO or DigitalOcean Spaces).

Onboarding Settings

Control what happens in the critical moment after a user's first login. This is where you shape the initial experience and reduce time-to-value.

• onboarding.mode — Three options:
  • prompt — Show an onboarding dialog asking the user to name their workspace. Good for B2B products where the organization name matters (it appears in invoices, team invitations, etc.).
  • auto — Automatically create a workspace using the name template. Good for products where the workspace is secondary (e.g., personal productivity tools) — get the user to value faster.
  • disabled — Do not create a workspace on signup. Use this when workspaces are created later through a separate flow (e.g., after payment).
• org_name_template — Template for auto-created workspace names. Default: {name}'s Team. The {name} variable is replaced with the user's name (e.g., "Alice's Team").
• landing_page — Where to redirect after onboarding completes. Default: /dashboard. Set it to /getting-started if you have a tutorial flow, or /projects/new if you want users to create something immediately.

Style Settings

Customize the look and feel of the entire application without touching CSS. These settings apply globally for all users.

• navigation — sidebar or horizontal. Sidebar navigation works better for apps with many sections. Horizontal (top nav) works better for simpler apps with fewer pages.
• default_theme — light, dark, or system. System follows the user's OS preference. Most B2B apps use light by default; developer tools often default to dark.
• content_width — fluid (full width) or contained (max-width centered). Fluid works for data-heavy dashboards; contained works for content-focused apps.
• theme_preset — Color palette preset. Options include zinc, slate, stone, gray, neutral, and others. Each preset defines a coordinated set of background, border, and text colors.
• border_radius — Controls how rounded corners are across all UI elements. Lower values (e.g., 0.25rem) give a sharper, more corporate look. Higher values (e.g., 0.75rem) give a softer, friendlier feel.
• sidebar_style — Visual style for the sidebar (when using sidebar navigation). Options include default, compact, and inset variants.
• content_style — Visual style for the main content area. Affects spacing, card styles, and overall density.

Notifications Settings

Global control over the in-app notification system.

• notifications.enabled — Master switch for in-app notifications. When disabled, no new notifications are created or displayed. Use this during maintenance windows or major migrations when you do not want users to be bombarded with system-generated notifications.

SaaS Settings

Fundamental configuration for how your product handles multi-tenancy. This decision shapes your entire data model, so set it early.

• tenant_mode — Two options:
  • organization — Multi-org mode (B2B). Users belong to one or more organizations. Data is scoped to organizations. Billing is per-organization. This is the right choice for team collaboration tools, project management apps, and anything where multiple people share a workspace.
  • personal — Personal workspace mode (B2C). Each user gets their own workspace automatically. There are no team features. Billing is per-user. This is the right choice for personal productivity tools, individual creator tools, and single-player apps.

Infra Settings

Infrastructure configuration that you would normally set in .env and deploy. Here, you can change it from the admin panel — useful for scaling up without re-deploying, or for quickly switching to a different cache backend when troubleshooting.

• queue_driver — How background jobs (emails, webhooks, exports) are processed:
  • sync — Jobs run immediately in the request. Simple but blocks the response. Only use for development.
  • database — Jobs are stored in a database table and processed by a worker. Good starting point for production — no extra infrastructure needed beyond your database.
  • redis — Jobs are pushed to Redis and processed by a worker. Faster than database, supports priorities and rate limiting. Use this when you have more than a few hundred jobs per minute.
  • sqs — Amazon SQS. Fully managed, auto-scaling. Use this when you need to handle thousands of jobs per minute without managing Redis infrastructure.
• cache_driver — Where frequently-accessed data is cached:
  • file — Cache stored on disk. Works everywhere but slow.
  • database — Cache stored in a database table. Better than file, no extra infrastructure.
  • redis — In-memory cache. Fast. The standard choice for production.
  • memcached — Alternative in-memory cache. Use if you already have Memcached infrastructure.
• session_driver — Where user sessions are stored. Same options as cache. Redis is recommended for production because sessions are fast to read and automatically expire.
• session_lifetime — How long a session lasts (in minutes) before the user must log in again. Default is 120 minutes. Set it higher (e.g., 10080 for one week) for consumer apps where convenience matters, or lower (e.g., 30) for security-sensitive apps.
• Connection details — When using Redis, Memcached, or SQS, you can configure the connection parameters (host, port, password, queue name, region) directly from the admin panel.

Utility Endpoints

Test Email

POST /api/admin/settings/test-email

{
    "to": "admin@example.com"
}

When to use: After configuring or changing your mail driver. This sends a real email through your current mail configuration, so you can verify that credentials are correct, SPF/DKIM is passing, and emails actually arrive in the inbox (not spam). Always test before going live with a new mail provider.

Flush Cache

POST /api/admin/cache/flush

When to use: After changing infrastructure settings (cache driver, session driver) or when cached data is stale. This clears all cached settings and application cache. Settings are re-read from the database on the next request. Also useful if you changed a setting but it does not seem to be taking effect — cached values might be overriding the new value.

Parse SAML Metadata

POST /api/admin/saml/parse-metadata

{
    "metadata_url": "https://idp.example.com/metadata.xml"
}

When to use: When an enterprise customer sends you their SAML metadata URL (they will say something like "here's our IdP metadata"). Instead of manually copying the entity ID, SSO URL, and certificate from an XML file, paste the URL here and the endpoint extracts everything automatically. The response contains the parsed values ready to be saved into SSO settings.