Project Settings

Each project has configurable settings for storage, email, authentication, database, and more. Changes require a project restart.

Accessing Settings

Via Web UI

1. Click on a project
2. Go to Settings tab
3. Select the category
4. Make changes
5. Click Save and restart

Via API

# Get all settings
curl https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key"

# Get specific category
curl "https://supascale.example.com/api/v1/projects/my-project/settings?category=smtp" \
  -H "X-API-Key: your-api-key"

Storage Settings

Configure file storage behavior:

Update via API

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "storage",
    "settings": {
      "fileSizeLimit": "100MB"
    }
  }'

SMTP Settings

Configure email delivery for authentication:

Example Configurations

SendGrid

{
  "category": "smtp",
  "settings": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "user": "apikey",
    "password": "your-sendgrid-api-key",
    "senderName": "My Application",
    "senderEmail": "[email protected]"
  }
}

Mailgun

{
  "category": "smtp",
  "settings": {
    "host": "smtp.mailgun.org",
    "port": 587,
    "user": "[email protected]",
    "password": "your-mailgun-password",
    "senderName": "My Application",
    "senderEmail": "[email protected]"
  }
}

Gmail

{
  "category": "smtp",
  "settings": {
    "host": "smtp.gmail.com",
    "port": 587,
    "user": "[email protected]",
    "password": "your-app-password",
    "senderName": "My Application",
    "senderEmail": "[email protected]"
  }
}

For Gmail, use an App Password instead of your regular password.

Auth Settings

Configure authentication behavior:

Update via API

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "auth",
    "settings": {
      "siteUrl": "https://myapp.com",
      "jwtExpiry": 7200,
      "disableSignup": false,
      "emailConfirmRequired": true
    }
  }'

OAuth Provider Settings

Configure social login providers for your project. For detailed setup instructions, see the OAuth documentation.

Supported Providers

Supascale supports 18 OAuth providers including Google, GitHub, Apple, Microsoft, Discord, and more.

Configuring a Provider

1. Click on a project
2. Go to Settings > OAuth Providers
3. Click the provider you want to enable
4. Enter your Client ID and Client Secret
5. Copy the Callback URL to your provider's developer console
6. Click Save
7. Restart the project

Example: Enable Google OAuth

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/oauth/google \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "clientId": "your-google-client-id.apps.googleusercontent.com",
    "clientSecret": "your-google-client-secret"
  }'

Viewing Configured Providers

curl https://supascale.example.com/api/v1/projects/my-project/oauth \
  -H "X-API-Key: your-api-key"

Response:

{
  "providers": [
    {
      "name": "google",
      "enabled": true,
      "configured": true
    },
    {
      "name": "github",
      "enabled": false,
      "configured": false
    }
  ]
}

OAuth credentials are encrypted before storage. See Encryption for details.

Connection Pooler Settings

Configure PgBouncer (requires pooler service enabled):

Pool Modes:

• session - Connection held for entire session
• transaction - Connection released after transaction
• statement - Connection released after each statement

Update via API

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "pooler",
    "settings": {
      "poolMode": "transaction",
      "defaultPoolSize": 25,
      "maxClientConnections": 200
    }
  }'

API Settings

Configure REST API behavior:

Update via API

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "api",
    "settings": {
      "maxRows": 2000,
      "dbSchema": "public,api"
    }
  }'

Database Settings

Configure PostgreSQL version and which network interface the database ports listen on.

The Listen on dropdown offers:

• Localhost only (127.0.0.1) — the ports accept connections from the server itself. Reach them from elsewhere with an SSH tunnel: ssh -L 54322:127.0.0.1:54322 user@your-server.
• All interfaces (0.0.0.0) — reachable on every address the server has, including its public IP.
• A specific interface (for example eth1 — 10.0.0.5 or a WireGuard address) — reachable on that address only.

The choice applies to both the direct port and the pooler port, and takes effect on the next restart. When you pick anything other than localhost, Supascale opens the two ports in ufw or firewalld for you and shows their firewall status on the page.

View Database Settings

curl "https://supascale.example.com/api/v1/projects/my-project/settings?category=database" \
  -H "X-API-Key: your-api-key"

Response:

{
  "success": true,
  "data": {
    "externalAccess": false,
    "bindAddress": "127.0.0.1",
    "postgresVersion": "15",
    "port": 54322,
    "poolerPort": 54329,
    "interfaces": [
      { "address": "203.0.113.5", "interfaceName": "eth0" },
      { "address": "10.8.0.1", "interfaceName": "wg0" }
    ],
    "firewall": {
      "type": "ufw",
      "active": true,
      "portsOpen": false,
      "portDetails": [
        { "port": 54322, "protocol": "tcp", "allowed": false },
        { "port": 54329, "protocol": "tcp", "allowed": false }
      ]
    }
  }
}

interfaces lists the addresses this server can bind right now; bindAddress must be 127.0.0.1, 0.0.0.0, or one of them.

Choose the Listen Address

Bind the database ports to one interface:

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "database",
    "settings": {
      "bindAddress": "10.8.0.1"
    }
  }'

The older "externalAccess": true / false form still works and maps to 0.0.0.0 / 127.0.0.1.

Security Warning: Anything other than localhost exposes your PostgreSQL ports to that network. Ensure your firewall is properly configured and use strong database passwords. Only do this if you need direct database connections from external tools or services — an SSH tunnel to the localhost binding is the safer option.

Change PostgreSQL Version

Upgrade or downgrade PostgreSQL version:

curl -X PUT https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "category": "database",
    "settings": {
      "postgresVersion": "17"
    }
  }'

Changing the PostgreSQL version requires a full project restart. Your data is preserved during the upgrade process.

Applying Changes

After modifying settings:

1. Click Save Changes (UI) or make API call
2. Restart the project for changes to take effect

# Via API
curl -X POST https://supascale.example.com/api/v1/projects/my-project/stop \
  -H "X-API-Key: your-api-key"

curl -X POST https://supascale.example.com/api/v1/projects/my-project/start \
  -H "X-API-Key: your-api-key"

Viewing Current Settings

Settings are returned with sensitive values masked:

curl https://supascale.example.com/api/v1/projects/my-project/settings \
  -H "X-API-Key: your-api-key"

Response:

{
  "storage": {
    "fileSizeLimit": "50MB"
  },
  "smtp": {
    "host": "smtp.sendgrid.net",
    "port": 587,
    "user": "apikey",
    "password": "********",
    "senderName": "My App",
    "senderEmail": "[email protected]"
  },
  "auth": {
    "siteUrl": "https://myapp.com",
    "jwtExpiry": 3600
  }
}

Best Practices

1. Test SMTP before enabling email confirmation
2. Use environment-specific settings for dev/staging/prod
3. Document your configuration for team reference
4. Backup settings before major changes