Settings

Manage Metabase instance settings and configuration

The Settings API allows you to view and modify Metabase instance settings programmatically. Settings control various aspects of your Metabase instance including email, authentication, appearance, and more.

Settings overview

Metabase settings are organized into categories:

• Email - SMTP configuration for email notifications
• Authentication - SSO, LDAP, and login settings
• Public sharing - Public links and embedding settings
• Slack - Slack integration configuration
• Maps - Custom map configuration
• Formatting - Date, time, and number formatting
• Localization - Language and timezone settings

Most settings endpoints require admin permissions.

Get all settings

Retrieve all instance settings.

GET /api/setting

curl

curl -X GET \
  https://your-metabase.com/api/setting \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Requires admin permissions. Returns all configurable settings with their current values.

Response

[
  {
    "key": "site-name",
    "value": "Metabase",
    "description": "The name used for this instance of Metabase.",
    "default": "Metabase",
    "type": "string"
  },
  {
    "key": "admin-email",
    "value": "[e-mail]",
    "description": "The email address users should be referred to if they encounter a problem.",
    "type": "string"
  }
]

Get specific setting

Get the value of a specific setting.

GET /api/setting/{key}

curl

curl -X GET \
  https://your-metabase.com/api/setting/site-name \
  -H 'X-Metabase-Session: SESSION_TOKEN'

Parameters

key · string · required

Setting key (e.g., “site-name”, “admin-email”)

Response

"Metabase"

Update setting

Update the value of a specific setting.

PUT /api/setting/{key}

curl

curl -X PUT \
  https://your-metabase.com/api/setting/site-name \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "value": "My Company Analytics"
  }'

Request body

value · required

New setting value (type depends on the setting)

Changing certain settings (like email or authentication) can affect all users. Test changes carefully.

Common settings

Site configuration

site-name · string

The name of your Metabase instance

site-url · string

The base URL where Metabase is hosted (e.g., “https://metabase.company.com”)

admin-email · string

Email address for admin contact

anon-tracking-enabled · boolean

Whether anonymous usage tracking is enabled

Email settings

email-smtp-host · string

SMTP server host

email-smtp-port · integer

SMTP server port

email-smtp-username · string

SMTP username

email-smtp-password · string

SMTP password

email-smtp-security · string

Security protocol: “none”, “tls”, or “starttls”

email-from-address · string

Email address to send from

Public sharing

enable-public-sharing · boolean

Enable public sharing of dashboards and questions

enable-embedding · boolean

Enable signed embedding

embedding-secret-key · string

Secret key for signing embedding tokens

Authentication

google-auth-client-id · string

Google OAuth client ID

ldap-enabled · boolean

Enable LDAP authentication

ldap-host · string

LDAP server host

ldap-port · integer

LDAP server port

Formatting

custom-formatting · object

Custom number and date formatting options

report-timezone · string

Default timezone for reports (e.g., “America/New_York”)

Update multiple settings

Update multiple settings at once.

PUT /api/setting

curl

curl -X PUT \
  https://your-metabase.com/api/setting \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "site-name": "My Company",
    "admin-email": "[e-mail]",
    "report-timezone": "America/Los_Angeles"
  }'

Request body

Provide a JSON object with setting keys and their new values:

{
  "site-name": "My Company Analytics",
  "admin-email": "[e-mail]",
  "enable-public-sharing": true
}

Test email settings

Test SMTP email configuration by sending a test email.

POST /api/email/test

curl

curl -X POST \
  https://your-metabase.com/api/email/test \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "email": "[e-mail]"
  }'

Request body

email · string · required

Email address to send test email to

Response

success · boolean

Whether the test email was sent successfully

error · string

Error message if sending failed

Environment variables

Many settings can be configured via environment variables:

# Site configuration
MB_SITE_NAME="My Company"
MB_SITE_URL="https://metabase.company.com"

# Email
MB_EMAIL_SMTP_HOST="smtp.gmail.com"
MB_EMAIL_SMTP_PORT=587
MB_EMAIL_SMTP_USERNAME="[e-mail]"
MB_EMAIL_SMTP_PASSWORD="your-password"
MB_EMAIL_SMTP_SECURITY="starttls"

# Public sharing
MB_ENABLE_PUBLIC_SHARING=true
MB_EMBEDDING_SECRET_KEY="your-secret-key"

Environment variables take precedence over database settings and cannot be changed via the API.

Setting types

Settings have different data types:

• string - Text values
• integer - Numeric values
• boolean - true/false values
• json - Complex object values
• csv - Comma-separated values

Reset settings

Reset a setting to its default value by setting it to null:

curl -X PUT \
  https://your-metabase.com/api/setting/site-name \
  -H 'Content-Type: application/json' \
  -H 'X-Metabase-Session: SESSION_TOKEN' \
  -d '{
    "value": null
  }'

Best practices

Settings management tips:

• Document any custom settings you configure
• Use environment variables for sensitive values
• Test email settings before relying on notifications
• Keep a backup of your configuration
• Review settings after upgrades
• Use descriptive site names for multiple instances

Error codes

400 Bad Request · error

Invalid setting value or type

403 Forbidden · error

Must be an admin to modify settings

404 Not Found · error

Setting key not found