Server Configuration

Frontier server configuration controls the core application behavior, network settings, authentication, and platform-level features. Configuration can be provided via a YAML file or environment variables with the FRONTIER_SERVICE_ prefix.

Configuration File

By default, Frontier looks for a configuration file. You can specify a custom config file:

frontier server start --config=/path/to/config.yaml

Environment Variables

All configuration options can be set using environment variables with the FRONTIER_SERVICE_ prefix:

export FRONTIER_SERVICE_APP_PORT=8000
export FRONTIER_SERVICE_DB_URL="postgres://user:pass@localhost:5432/frontier"

Core Configuration

Version

version

integer

default:"1"

Configuration file version number. Used for backward compatibility.

Logging

log.level

string

default:"info"

Logging level for the application.Options: debug, info, warning, error, fatal

log.audit_events

string

default:"none"

Controls where audit events are logged.Options:

none - Audit events are not logged
stdout - Log audit events to standard output
db - Store audit events in the database

log.ignored_audit_events

array

default:"[]"

List of audit event names to ignore from logging.

log:
  ignored_audit_events:
    - "app.user.created"
    - "app.permission.checked"

Application Settings

Network Configuration

app.host

string

default:"127.0.0.1"

Host address for the Frontier application to bind to.

app.port

integer

default:"8000"

required

Port number for HTTP/REST API communication.

app.grpc.port

integer

default:"8001"

required

Port number for gRPC communication.

app.grpc.max_recv_msg_size

integer

default:"33554432"

Maximum message size in bytes that the gRPC server can receive (32MB default).

app.grpc.max_send_msg_size

integer

default:"33554432"

Maximum message size in bytes that the gRPC server can send (32MB default).

app.connect.port

integer

default:"8002"

Port number for Connect protocol communication.

app.metrics_port

integer

default:"9000"

Port number for Prometheus metrics exposition.

TLS Configuration

app.grpc.tls_cert_file

string

Path to TLS certificate file for gRPC server.

app:
  grpc:
    tls_cert_file: "/etc/frontier/certs/server-cert.pem"
    tls_key_file: "/etc/frontier/certs/server-key.pem"
    tls_client_ca_file: "/etc/frontier/certs/ca-cert.pem"

app.grpc.tls_key_file

string

Path to TLS private key file for gRPC server.

app.grpc.tls_client_ca_file

string

Path to CA certificate for client certificate verification.

Profiling & Monitoring

app.profiler

boolean

default:"false"

Enable pprof endpoints for CPU, memory, and mutex profiling at /debug/pprof.

Only enable in development or controlled environments as it exposes runtime information.

CORS Configuration

app.cors.allowed_origins

array

required

List of origins allowed for Cross-Origin Resource Sharing.

app:
  cors:
    allowed_origins:
      - "https://app.example.com"
      - "https://admin.example.com"
      # Use "*" to allow all origins (not recommended for production)

app.cors.allowed_methods

array

HTTP methods allowed for CORS requests.

app:
  cors:
    allowed_methods:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE

app.cors.allowed_headers

array

HTTP headers allowed in CORS requests.

app:
  cors:
    allowed_headers:
      - Authorization
      - Content-Type
      - X-Requested-With

app.cors.exposed_headers

array

HTTP headers that browsers are allowed to access.

app:
  cors:
    exposed_headers:
      - Content-Type
      - X-Request-Id

Authentication Configuration

Session Management

app.authentication.session.hash_secret_key

string

required

Secret key for session hash validation (must be exactly 32 characters).

app:
  authentication:
    session:
      hash_secret_key: "hash-secret-should-be-32-chars--"

Generate a secure random string for production. Never commit secrets to version control.

app.authentication.session.block_secret_key

string

required

Secret key for session encryption (must be exactly 32 characters).

app:
  authentication:
    session:
      block_secret_key: "block-secret-should-be-32-chars-"

app.authentication.session.domain

string

Domain for session cookies. If not set, defaults to request origin host.

app.authentication.session.same_site

string

default:"lax"

SameSite policy for session cookies.Options: "" (empty), lax, strict, none

app.authentication.session.validity

duration

default:"720h"

Session validity duration (default: 30 days).

app:
  authentication:
    session:
      validity: "168h"  # 7 days

app.authentication.session.secure

boolean

default:"false"

Enable secure flag for cookies (requires HTTPS).

Set to true in production when using HTTPS.

app.authentication.session.headers

object

Custom headers for collecting session metadata.

app:
  authentication:
    session:
      headers:
        client_ip: "x-forwarded-for"
        client_country: "x-frontier-country"
        client_city: "x-frontier-city"
        client_user_agent: "User-Agent"

JWT Token Configuration

app.authentication.token.rsa_path

string

Path to RSA private key for JWT signing. Generate using frontier server keygen.

app:
  authentication:
    token:
      rsa_path: "/etc/frontier/keys/rsa"

If not specified, JWT access tokens will be disabled.

app.authentication.token.rsa_base64

string

Base64-encoded RSA private key. Alternative to rsa_path for containerized deployments.

app.authentication.token.iss

string

default:"http://localhost.frontier"

Issuer claim (iss) added to JWT tokens.

app.authentication.token.validity

duration

default:"1h"

JWT token validity duration.

app.authentication.token.claims.add_org_ids

boolean

default:"true"

Include user’s organization IDs in JWT claims.

app.authentication.token.claims.add_user_email

boolean

default:"true"

Include user email in JWT claims.

app.authentication.token.claims.add_session_id

boolean

default:"true"

Include session ID in JWT claims.

Callback URLs

app.authentication.callback_urls

array

required

Public-facing URLs for OAuth callback redirects and email link verification.

app:
  authentication:
    callback_urls:
      - "http://localhost:8000/v1beta1/auth/callback"
      - "https://api.example.com/v1beta1/auth/callback"

The first URL is used by default. Additional URLs can be selected per-strategy using query parameters.

app.authentication.authorized_redirect_urls

array

URLs where users can be redirected after successful authentication.

app:
  authentication:
    authorized_redirect_urls:
      - "https://app.example.com/dashboard"
      - "https://app.example.com/home"

OIDC Configuration

app.authentication.oidc_config

object

OpenID Connect provider configurations. Multiple providers can be configured.

app:
  authentication:
    oidc_config:
      google:
        client_id: "xxxxx.apps.googleusercontent.com"
        client_secret: "xxxxx"
        issuer_url: "https://accounts.google.com"
        validity: "10m"
      github:
        client_id: "github-client-id"
        client_secret: "github-client-secret"
        issuer_url: "https://github.com"
        validity: "10m"

Email Authentication

app.authentication.mail_otp

object

Configuration for one-time password (OTP) email authentication.

app:
  authentication:
    mail_otp:
      subject: "Frontier - Login Code"
      body: "Your login code: <h2>{{.Otp}}</h2>"
      validity: "15m"

The body is a Go template with {{.Otp}} variable.

app.authentication.mail_link

object

Configuration for magic link email authentication.

app:
  authentication:
    mail_link:
      subject: "Frontier Login - One time link"
      body: "Click to login: <a href='{{.Link}}'>Login</a>"
      validity: "15m"

The body is a Go template with {{.Link}} variable.

Passkey Configuration

app.authentication.passkey.rpdisplayname

string

Display name for the Relying Party (your application name).

app.authentication.passkey.rpid

string

Relying Party ID (typically your domain without scheme and port).

app:
  authentication:
    passkey:
      rpid: "example.com"

app.authentication.passkey.rporigins

array

List of fully qualified origins permitted for passkey authentication.

app:
  authentication:
    passkey:
      rporigins:
        - "https://example.com"
        - "https://app.example.com"

Test Users

app.authentication.test_users.enabled

boolean

default:"false"

Enable test user authentication for development/testing.

Never enable in production environments.

app.authentication.test_users.domain

string

Email domain for test users (e.g., example.com).

app.authentication.test_users.otp

string

Fixed OTP for test users.

Admin Configuration

app.admin.users

array

Email addresses, UUIDs, or slugs of users to promote as platform superusers.

app:
  admin:
    users:
      - "[email protected]"
      - "[email protected]"

If a user exists, they’re promoted to superuser. If an email is provided for a non-existent user, a new account is created.

Resources Configuration

app.resources_config_path

string

Path to resources configuration files with scheme prefix.

app:
  resources_config_path: "file:///tmp/resources_config"
  # Or for GCS:
  # resources_config_path: "gs://frontier-bucket/resources_config"

app.resources_config_path_secret

string

Secret for accessing resources configuration.

app:
  resources_config_path_secret: "env://RESOURCE_CONFIG_SECRET"
  # Or from file:
  # resources_config_path_secret: "file:///opt/auth.json"
  # Or direct value:
  # resources_config_path_secret: "val://user:password"

Webhook Configuration

app.webhook.encryption_key

string

required

Encryption key for webhook endpoint secrets stored in database (must be 32 characters).

app:
  webhook:
    encryption_key: "webhook-secret-32-characters--"

This encrypts the endpoint secrets, not the webhook payloads themselves.

Development Settings

app.identity_proxy_header

string

HTTP header name containing user’s email for identity proxying.

app:
  identity_proxy_header: "X-Frontier-Email"

CRITICAL: This bypasses ALL authorization checks. NEVER use in production.

Admin UI Configuration

ui.port

integer

default:"8100"

Port for the Admin UI web interface.

ui.title

string

default:"Frontier Admin"

Title displayed in the browser tab.

ui.logo

string

URL or path to logo image for the login page.

ui.app_url

string

Base URL for showing users their full organization URL.

ui.token_product_id

string

Product ID to use for adding credits in the UI.

ui.organization_types

array

List of organization industry types for UI dropdowns.

ui:
  organization_types:
    - "Technology"
    - "Healthcare"
    - "Finance"
    - "Education"

New Relic Integration

new_relic.enabled

boolean

default:"false"

Enable New Relic APM integration.

new_relic.app_name

string

default:"Frontier"

Application name in New Relic.

new_relic.license

string

New Relic license key.

Complete Example

version: 1

log:
  level: info
  audit_events: db
  ignored_audit_events:
    - "app.permission.checked"

new_relic:
  enabled: false
  app_name: "Frontier"
  license: "NEWRELIC_LICENSE_KEY"

ui:
  port: 8100
  title: "Frontier Admin"
  logo: "https://example.com/logo.png"
  app_url: "https://app.example.com"
  organization_types:
    - "Technology"
    - "Healthcare"

app:
  host: "0.0.0.0"
  port: 8000
  grpc:
    port: 8001
    max_recv_msg_size: 33554432
    max_send_msg_size: 33554432
  connect:
    port: 8002
  metrics_port: 9000
  profiler: false
  
  cors:
    allowed_origins:
      - "https://app.example.com"
    allowed_methods:
      - GET
      - POST
      - PUT
      - PATCH
      - DELETE
    allowed_headers:
      - Authorization
      - Content-Type
    exposed_headers:
      - Content-Type
  
  authentication:
    callback_urls:
      - "https://api.example.com/v1beta1/auth/callback"
    authorized_redirect_urls:
      - "https://app.example.com/dashboard"
    
    session:
      hash_secret_key: "hash-secret-should-be-32-chars--"
      block_secret_key: "block-secret-should-be-32-chars-"
      domain: "example.com"
      same_site: "lax"
      validity: "720h"
      secure: true
      headers:
        client_ip: "x-forwarded-for"
        client_country: "x-frontier-country"
        client_city: "x-frontier-city"
        client_user_agent: "User-Agent"
    
    token:
      rsa_path: "/etc/frontier/keys/rsa"
      iss: "https://api.example.com"
      validity: "1h"
      claims:
        add_org_ids: true
        add_user_email: true
        add_session_id: true
    
    oidc_config:
      google:
        client_id: "xxxxx.apps.googleusercontent.com"
        client_secret: "xxxxx"
        issuer_url: "https://accounts.google.com"
        validity: "10m"
    
    mail_otp:
      subject: "Your Login Code"
      body: "Use this code to login: <h2>{{.Otp}}</h2>"
      validity: "15m"
    
    mail_link:
      subject: "Your Login Link"
      body: "Click here to login: <a href='{{.Link}}'>Login</a>"
      validity: "15m"
    
    passkey:
      rpdisplayname: "Example App"
      rpid: "example.com"
      rporigins:
        - "https://example.com"
        - "https://app.example.com"
  
  admin:
    users:
      - "[email protected]"
  
  webhook:
    encryption_key: "webhook-secret-32-characters--"

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

Server Configuration

Configuration File

Environment Variables

Core Configuration

Version

Logging

Application Settings

Network Configuration

TLS Configuration

Profiling & Monitoring

CORS Configuration

Authentication Configuration

Session Management

JWT Token Configuration

Callback URLs

OIDC Configuration

Email Authentication

Passkey Configuration

Test Users

Admin Configuration

Resources Configuration

Webhook Configuration

Development Settings

Admin UI Configuration

New Relic Integration

Complete Example

See Also

Build docs developers (and LLMs) love

Overview

Core Concepts

Authentication

Authorization

Organization Management

Billing

Guides

Configuration

​Configuration File

​Environment Variables

​Core Configuration

​Version

​Logging

​Application Settings

​Network Configuration

​TLS Configuration

​Profiling & Monitoring

​CORS Configuration

​Authentication Configuration

​Session Management

​JWT Token Configuration

​Callback URLs

​OIDC Configuration

​Email Authentication

​Passkey Configuration

​Test Users

​Admin Configuration

​Resources Configuration

​Webhook Configuration

​Development Settings

​Admin UI Configuration

​New Relic Integration

​Complete Example

​See Also

Build docs developers (and LLMs) love

Configuration File

Environment Variables

Core Configuration

Version

Logging

Application Settings

Network Configuration

TLS Configuration

Profiling & Monitoring

CORS Configuration

Authentication Configuration

Session Management

JWT Token Configuration

Callback URLs

OIDC Configuration

Email Authentication

Passkey Configuration

Test Users

Admin Configuration

Resources Configuration

Webhook Configuration

Development Settings

Admin UI Configuration

New Relic Integration

Complete Example

See Also