HTTP Server Configuration

Configure HTTP/HTTPS listening, named sockets, and TLS certificates. The unified HTTP server handles all HTTP-based channels.

Related:

• REST Channel — REST API binds to the unified HTTP server
• GraphQL Channel — GraphQL API binds to the unified HTTP server
• MCP Channel — MCP (Model Context Protocol) uses the GraphQL transport
• Monitoring — Monitoring endpoints can be isolated on a dedicated socket
• Upgrading IdentityScribe — Migration notes for socket/endpoints changes

IdentityScribe uses a unified HTTP server for all HTTP traffic:

• REST API (/api/*)
• GraphQL API (/graphql)
• MCP (/mcp) — Model Context Protocol, uses GraphQL transport
• Monitoring endpoints (/metrics, /observe/*, /livez, /readyz, etc.)

All channels bind to the same server via named sockets. By default, everything uses the @default socket on port 8080.

flowchart TB
    subgraph Config["http { } Configuration"]
        Default["@default socket<br/>port: 8080, host: auto"]
        Named["http.sockets.* (opt-in)"]
    end

    subgraph Channels["Channels"]
        REST["channels.rest"]
        GQL["channels.graphql"]
        MCP["channels.mcp"]
        MON["monitoring.*"]
    end

    Default --> REST
    Default --> GQL
    Default --> MCP
    Default --> MON
    Named -.->|"socket = name"| REST
    Named -.->|"socket = name"| GQL
    Named -.->|"socket = name"| MCP
    Named -.->|"socket = name"| MON

The primary socket is configured at http {} root level:

http {
  # Port for all HTTP traffic (default: 8080)
  port = 8080
  port = ${?SCRIBE_HTTP_PORT}

  # Host binding
  # "auto" resolves based on app.mode:
  #   - dev/test/local: localhost (safe default)
  #   - production: 0.0.0.0 (all interfaces)
  host = auto
  host = ${?SCRIBE_HTTP_HOST}
}

Define additional sockets under http.sockets.* for network separation:

http.sockets.internal {
  port = 9001
  port = ${?SCRIBE_INTERNAL_PORT}
  host = "localhost"
}

Named sockets inherit all settings from http {} automatically. Only override what differs.

Channels reference sockets by name. If not specified, they use @default.

channels.rest {
  enabled = true

  # Socket for REST API (default: @default)
  socket = ${?SCRIBE_REST_SOCKET}
}

Monitoring supports per-endpoint socket configuration:

monitoring {
  # Default socket for all monitoring (falls back to @default)
  socket = ${?SCRIBE_MONITORING_SOCKET}

  # Per-endpoint overrides (each falls back to monitoring.socket)
  prometheus.socket = ${?SCRIBE_PROMETHEUS_SOCKET}
  observe.socket = ${?SCRIBE_OBSERVE_SOCKET}
  health.socket = ${?SCRIBE_HEALTH_SOCKET}
}

Channels can bind to multiple sockets using array syntax:

# HOCON array
monitoring.socket = ["@default", "internal"]

# Environment variable (comma-separated)
SCRIBE_MONITORING_SOCKET="@default,internal"

Everything on one port — simplest setup:

http {
  port = 8080
  host = "0.0.0.0"
}

# All channels use @default automatically

curl http://localhost:8080/api/entries/user
curl http://localhost:8080/metrics
curl http://localhost:8080/readyz

Keep REST public, monitoring internal:

http {
  port = 8080
  host = "0.0.0.0"

  sockets.internal {
    port = 9001
    host = "localhost"
  }
}

monitoring.socket = "internal"

# Public REST API
curl http://public-ip:8080/api/entries/user

# Internal monitoring (localhost only)
curl http://localhost:9001/metrics
curl http://localhost:9001/readyz

Note: The bundled monitoring stack (monitoring/docker, monitoring/helm) uses this pattern with monitoring on port 9001.

For development, you may want monitoring endpoints available on both the default and internal sockets to avoid confusion when accidentally using the wrong port:

http {
  port = 8080
  sockets.monitoring { port = 9001 }
}

monitoring {
  socket = "monitoring"

  # Expose on BOTH sockets for dev convenience
  observe.socket = ["@default", "monitoring"]
  health.socket = ["@default", "monitoring"]
  prometheus.socket = ["@default", "monitoring"]
}

This configuration:

• Keeps the production separation (monitoring.socket = "monitoring")
• Overrides individual endpoints to be available on both sockets
• Prevents 404 confusion when hitting the wrong port during development

The config/dev-local.conf uses this pattern.

Enable HTTPS on the default socket:

http {
  port = 443
  ssl {
    enabled = true
    cert = "/path/to/server.pem"
    key = "/path/to/server.key"
  }
}

Require client certificates for API access (applies to REST, GraphQL, and MCP):

http {
  port = 8443
  ssl {
    enabled = true
    cert = "/path/to/server.pem"
    key = "/path/to/server.key"
    ca = "/path/to/client-ca.pem"
    client-auth = "REQUIRED"
  }
}

Settings marked as inheritable flow from http {} to named sockets:

Override specific settings in a named socket:

http {
  concurrency-limit.max-limit = 200

  sockets.internal {
    # Inherits concurrency-limit from http {}
    port = 9001
    # Override only content-encoding
    content-encoding.gzip.enabled = false
  }
}

If upgrading from a version that used separate monitoring configuration:

Before (old config):

monitoring {
  hostname = "localhost"
  port = 9001
}

channels.rest {
  listen = [{ port = 8080, host = "0.0.0.0" }]
}

After (new config):

http {
  port = 8080
  host = "0.0.0.0"

  sockets.internal {
    port = 9001
    host = "localhost"
  }
}

monitoring.socket = "internal"
# REST uses @default automatically

Or for simpler deployments where everything shares one port:

http {
  port = 8080
  host = "0.0.0.0"
}
# Everything uses @default — no named sockets needed

• Configuration Guide — General configuration reference
• Deployment Guide — Installation and deployment
• Monitoring Guide — Operational monitoring workflows
• REST Channel Guide — REST API configuration