Channels

Channels

GraphQL API channel configuration

The GraphQL channel exposes directory operations via GraphQL with:

• Collection queries: users(filter: …) { nodes { … } }
• Single lookup: user(id: ”…”) { … }
• Schema introspection: GET /graphql.sdl, GET /graphql.json
• GraphiQL UI: GET /graphql (Accept: text/html)

The base path is fixed at /graphql.

Automatic Persisted Queries (APQ)

APQ reduces bandwidth by allowing clients to send SHA256 hashes instead of full query strings after initial registration. Flow:

• Client sends POST with query + hash (registers query in cache)
• Subsequent requests send only the hash (GET or POST)
• On cache miss, client retries with full query

Enable APQ support

auto = enabled when GraphQL channel is enabled

true = always enabled, false = always disabled

Priority: SCRIBE_GRAPHQL_APQ_ENABLED > config

channels.graphql.apq.enabled = "auto"
channels.graphql.apq.enabled = ${?SCRIBE_GRAPHQL_APQ_ENABLED}

Maximum number of cached queries (LRU eviction when exceeded)

Priority: SCRIBE_GRAPHQL_APQ_MAX_SIZE > config

channels.graphql.apq.max-size = 1000
channels.graphql.apq.max-size = ${?SCRIBE_GRAPHQL_APQ_MAX_SIZE}

Cache entry TTL (expireAfterAccess, keeps hot queries longer)

Priority: SCRIBE_GRAPHQL_APQ_TTL > config

channels.graphql.apq.ttl = 10h
channels.graphql.apq.ttl = ${?SCRIBE_GRAPHQL_APQ_TTL}

Query Parameter Defaults

Applied when the client omits the parameter. Client-provided values override these defaults except for max-limit which always caps. Default page size when no limit/first/last specified (configurable, default: 25)

Priority: SCRIBE_GRAPHQL_DEFAULT_LIMIT > config

channels.graphql.default-limit = 25
channels.graphql.default-limit = ${?SCRIBE_GRAPHQL_DEFAULT_LIMIT}

Enable the GraphQL channel

Priority: SCRIBE_GRAPHQL_ENABLED > config

channels.graphql.enabled = false
channels.graphql.enabled = ${?SCRIBE_GRAPHQL_ENABLED}

Query analysis limits (applied after parsing, before execution). These prevent queries that would consume excessive resources.

Maximum query complexity (prevents wide queries with many fields). Complexity is calculated as sum of fields selected. Set to 0 to disable. Tune based on staging logs (start with p95 + headroom).

Priority: SCRIBE_GRAPHQL_LIMITS_MAX_COMPLEXITY > config

channels.graphql.limits.max-complexity = 500
channels.graphql.limits.max-complexity = ${?SCRIBE_GRAPHQL_LIMITS_MAX_COMPLEXITY}

Maximum query depth (prevents deeply nested queries). Default 15 allows introspection queries (required by GraphiQL). Set to 0 to disable depth checking.

Priority: SCRIBE_GRAPHQL_LIMITS_MAX_DEPTH > config

channels.graphql.limits.max-depth = 15
channels.graphql.limits.max-depth = ${?SCRIBE_GRAPHQL_LIMITS_MAX_DEPTH}

Maximum entries per request (caps client-provided limit, configurable, default: 1000)

Priority: SCRIBE_GRAPHQL_MAX_LIMIT > config

channels.graphql.max-limit = 1000
channels.graphql.max-limit = ${?SCRIBE_GRAPHQL_MAX_LIMIT}

Query Security Limits

Protection against denial-of-service through excessive query complexity. These limits apply at different stages of query processing. Parser-level DoS limits (applied before query analysis). These are the first line of defense against malicious payloads.

Maximum query characters (prevents excessive parsing time/memory).

Priority: SCRIBE_GRAPHQL_PARSER_MAX_CHARACTERS > config

channels.graphql.parser.max-characters = 1048576
channels.graphql.parser.max-characters = ${?SCRIBE_GRAPHQL_PARSER_MAX_CHARACTERS}

Maximum query tokens (prevents parser CPU exhaustion).

Priority: SCRIBE_GRAPHQL_PARSER_MAX_TOKENS > config

channels.graphql.parser.max-tokens = 15000
channels.graphql.parser.max-tokens = ${?SCRIBE_GRAPHQL_PARSER_MAX_TOKENS}

Socket reference for GraphQL API.

Use a named socket from http.sockets.* or omit for @default.

Priority: SCRIBE_GRAPHQL_SOCKET > config

channels.graphql.socket = ${?SCRIBE_GRAPHQL_SOCKET}

GraphiQL UI configuration

GraphiQL v5 provides an interactive GraphQL query builder with Monaco Editor and optional plugins (Explorer, History). Assets are bundled with the app by default (offline-safe, no external network). Use asset {} block to override with CDN URLs.

External asset configuration (CDN override). By default, GraphiQL assets are bundled with the app. If configured, all fields are required. SRI (Subresource Integrity) hash prevents supply-chain attacks.

Subresource Integrity hash for the CSS stylesheet.

Example: "sha512-..."

channels.graphql.ui.asset.css-sri = null

CDN URL for GraphiQL CSS stylesheet.

Example: "https://cdn.example.com/graphiql/5.2.0/graphiql.css"

channels.graphql.ui.asset.css-url = null

Subresource Integrity hash for the JavaScript bundle.

Example: "sha512-..."

channels.graphql.ui.asset.js-sri = null

CDN URL for GraphiQL JavaScript bundle.

Example: "https://cdn.example.com/graphiql/5.2.0/graphiql.bundle.js"

channels.graphql.ui.asset.js-url = null

Dark mode (Monaco editor theme)

Priority: SCRIBE_GRAPHQL_UI_DARK_MODE > config

channels.graphql.ui.dark-mode = false
channels.graphql.ui.dark-mode = ${?SCRIBE_GRAPHQL_UI_DARK_MODE}

Show variables/headers panel by default

auto = show in dev, hide in prod

true = always show, false = always hide

Priority: SCRIBE_GRAPHQL_UI_EDITOR_TOOLS > config

channels.graphql.ui.default-editor-tools-visibility = "auto"
channels.graphql.ui.default-editor-tools-visibility = ${?SCRIBE_GRAPHQL_UI_EDITOR_TOOLS}

Enable GraphiQL UI

auto = enabled in dev/test, disabled in prod (prod-safe default)

Priority: SCRIBE_GRAPHQL_UI_ENABLED > config

channels.graphql.ui.enabled = "auto"
channels.graphql.ui.enabled = ${?SCRIBE_GRAPHQL_UI_ENABLED}

Plugins configuration

Enable Explorer plugin (visual query builder) Great for non-developers to explore schema visually

Priority: SCRIBE_GRAPHQL_UI_EXPLORER > config

channels.graphql.ui.plugins.explorer = true
channels.graphql.ui.plugins.explorer = ${?SCRIBE_GRAPHQL_UI_EXPLORER}

Enable History plugin (query history sidebar)

Priority: SCRIBE_GRAPHQL_UI_HISTORY > config

channels.graphql.ui.plugins.history = true
channels.graphql.ui.plugins.history = ${?SCRIBE_GRAPHQL_UI_HISTORY}

LDAP channel configuration

The LDAP channel exposes directory operations via LDAP v3 protocol with:

• Standard LDAP search, compare, and bind operations
• Simple Paged Results and VLV controls for pagination
• Server-Side Sorting (SSS) control
• LDAPS (TLS) for secure connections
• Client certificate authentication

Settings inherit from the shared ldap configuration block.

Connection Hints (channel-specific overrides)

Override database.connection-hints defaults for LDAP queries only. Values here are merged with database defaults (channel values win).

Lock acquisition timeout

Priority: SCRIBE_LDAP_LOCK_TIMEOUT > config > database.connection-hints

channels.ldap.connection-hints.lock-timeout = ${?SCRIBE_LDAP_LOCK_TIMEOUT}

Session flags (comma-separated): force-custom-plan, jit-off

Priority: SCRIBE_LDAP_SESSION_FLAGS > config > database.connection-hints

channels.ldap.connection-hints.session-flags = ${?SCRIBE_LDAP_SESSION_FLAGS}

Statement execution timeout (prevents runaway queries)

Priority: SCRIBE_LDAP_STATEMENT_TIMEOUT > config > database.connection-hints

channels.ldap.connection-hints.statement-timeout = ${?SCRIBE_LDAP_STATEMENT_TIMEOUT}

PostgreSQL work_mem per-query memory

Priority: SCRIBE_LDAP_WORK_MEM > config > database.connection-hints

channels.ldap.connection-hints.work-mem = ${?SCRIBE_LDAP_WORK_MEM}

Specifies the timeout in seconds that should be used if the SO_LINGER socket option is enabled. The value must be between 0 and 65535, inclusive.

Priority: SCRIBE_LDAP_LINGER_TIMEOUT_SECONDS > config

channels.ldap.linger-timeout-seconds = ${?SCRIBE_LDAP_LINGER_TIMEOUT_SECONDS}

Specifies the address on which to listen for client connections. The provided value must be a valid IP address or hostname. It may be null to indicate that it should listen on all available addresses on all interfaces.

channels.ldap.listen.item.host = null

Specifies the port number on which to listen for client connections. The provided value must be between 1 and 65535, or it may be 0 to indicate that the JVM should select a free port on the system.

channels.ldap.listen.item.port = 10389

Enable SSL/TLS for the listener. Presence of this block enables LDAPS. Inherits from the shared ssl configuration (ssl.ca, ssl.cert, ssl.key, ssl.password).

Specifies whether the server should request that the client present its own certificate chain during TLS negotiation. This will be ignored for non-TLS-based connections.

channels.ldap.listen.item.ssl.request-client-certificate = false

Indicates whether the server should require that the client present its own certificate chain during TLS negotiation and should fail negotiation if no certificate chain was provided. This will be ignored for non-TLS-based connections, and it will also be ignored if request-client-certificate is false.

channels.ldap.listen.item.ssl.require-client-certificate = false

Connection Limits

Configure limits on connections and message sizes. Specifies the maximum number of concurrent connections that the server will allow. If a client tries to establish a new connection while the server already has the maximum number of concurrent connections, then the new connection will be rejected. A value that is less than or equal to zero indicates no limit.

Priority: SCRIBE_LDAP_MAX_CONNECTIONS > config

channels.ldap.max-connections = ${?SCRIBE_LDAP_MAX_CONNECTIONS}

Specifies the maximum size in bytes for LDAP messages that will be accepted by this server. A value that is less than or equal to zero will use the maximum allowed message size.

Priority: SCRIBE_LDAP_MAX_MESSAGE_SIZE_BYTES > config

channels.ldap.max-message-size-bytes = ${?SCRIBE_LDAP_MAX_MESSAGE_SIZE_BYTES}

Buffer Sizes

Configure socket buffer sizes for performance tuning. Specifies the receive buffer size that should be used for sockets accepted by the server. A value less than or equal to zero indicates that the default receive buffer size should be used.

Priority: SCRIBE_LDAP_RECEIVE_BUFFER_SIZE > config

channels.ldap.receive-buffer-size = ${?SCRIBE_LDAP_RECEIVE_BUFFER_SIZE}

Specifies the send buffer size that should be used for sockets accepted by the listener. A value less than or equal to zero indicates that the default send buffer size should be used.

Priority: SCRIBE_LDAP_SEND_BUFFER_SIZE > config

channels.ldap.send-buffer-size = ${?SCRIBE_LDAP_SEND_BUFFER_SIZE}

Indicates whether to use the TCP_NODELAY socket option for sockets accepted by the server. When enabled, disables Nagle’s algorithm for lower latency at the cost of more packets.

Priority: SCRIBE_LDAP_TCP_NO_DELAY > config

channels.ldap.tcp-no-delay = ${?SCRIBE_LDAP_TCP_NO_DELAY}

Socket Options

Fine-tune TCP connection behavior for LDAP connections. Specifies whether to use the SO_KEEPALIVE socket option for sockets accepted by the server. When enabled, the system will periodically probe idle connections to detect broken connections.

Priority: SCRIBE_LDAP_USE_KEEP_ALIVE > config

channels.ldap.use-keep-alive = ${?SCRIBE_LDAP_USE_KEEP_ALIVE}

Specifies whether to use the SO_LINGER socket option for sockets accepted by the server. When enabled, the socket will wait for pending data to be sent before closing.

Priority: SCRIBE_LDAP_USE_LINGER > config

channels.ldap.use-linger = ${?SCRIBE_LDAP_USE_LINGER}

Specifies whether to use the SO_REUSEADDR socket option for sockets accepted by the server. When enabled, allows the socket to bind to an address that is already in use.

Priority: SCRIBE_LDAP_USE_REUSE_ADDRESS > config

channels.ldap.use-reuse-address = ${?SCRIBE_LDAP_USE_REUSE_ADDRESS}

MCP (Model Context Protocol) channel configuration

The MCP channel exposes directory operations to AI coding assistants via:

• Tools: describe, search, help, ref
• Prompts: usage guide, filter syntax, troubleshooting
• Resources: OpenAPI spec, GraphQL schema, reference index

Works with Cursor, Claude Desktop, VS Code, Windsurf, and other MCP clients. The endpoint is fixed at /mcp.

Query Parameter Defaults

Applied when the client omits the parameter. Default page size for search results (configurable, default: 25)

Priority: SCRIBE_MCP_DEFAULT_LIMIT > config

channels.mcp.default-limit = 25
channels.mcp.default-limit = ${?SCRIBE_MCP_DEFAULT_LIMIT}

Enable the MCP channel

Priority: SCRIBE_MCP_ENABLED > config

channels.mcp.enabled = false
channels.mcp.enabled = ${?SCRIBE_MCP_ENABLED}

Maximum entries per search request (caps client-provided limit, default: 100)

Priority: SCRIBE_MCP_MAX_LIMIT > config

channels.mcp.max-limit = 100
channels.mcp.max-limit = ${?SCRIBE_MCP_MAX_LIMIT}

Socket reference(s) for MCP channel.

Can be a single name, comma-separated list, or HOCON list. Use named sockets from http.sockets.* or omit for @default.

Priority: SCRIBE_MCP_SOCKET > config

Examples:

socket = "admin"           # Single socket

socket = "admin, public"   # Comma-separated

socket = ["admin", "public"]  # HOCON list

channels.mcp.socket = ${?SCRIBE_MCP_SOCKET}

REST API channel configuration

The REST channel exposes directory operations via HTTP/JSON with:

• Collection search: GET /api/entries/{entry_type}
• Single lookup: GET /api/entries/{entry_type}/{id}
• OpenAPI UI/spec: GET /api

The base path is fixed at /api. Customers needing a different external path can use a reverse proxy for path rewriting.

Connection Hints (channel-specific overrides)

Override database.connection-hints defaults for REST queries only. Values here are merged with database defaults (channel values win).

Lock acquisition timeout

Priority: SCRIBE_REST_LOCK_TIMEOUT > config > database.connection-hints

channels.rest.connection-hints.lock-timeout = ${?SCRIBE_REST_LOCK_TIMEOUT}

Session flags (comma-separated): force-custom-plan, jit-off

Priority: SCRIBE_REST_SESSION_FLAGS > config > database.connection-hints

channels.rest.connection-hints.session-flags = ${?SCRIBE_REST_SESSION_FLAGS}

Statement execution timeout (prevents runaway queries)

Priority: SCRIBE_REST_STATEMENT_TIMEOUT > config > database.connection-hints

channels.rest.connection-hints.statement-timeout = ${?SCRIBE_REST_STATEMENT_TIMEOUT}

PostgreSQL work_mem per-query memory

Priority: SCRIBE_REST_WORK_MEM > config > database.connection-hints

channels.rest.connection-hints.work-mem = ${?SCRIBE_REST_WORK_MEM}

Default count mode: exact, estimated, none (configurable, default: “estimated”)

Priority: SCRIBE_REST_DEFAULT_COUNT > config

channels.rest.default-count = "estimated"
channels.rest.default-count = ${?SCRIBE_REST_DEFAULT_COUNT}

Default attribute selection (configurable)

• null (default): return all user attributes (equivalent to LDAP ”*”)
• “cn,mail,sn”: return only specified attributes
• ”*,+”: return all user and operational attributes

Priority: SCRIBE_REST_DEFAULT_FIELDS > config

channels.rest.default-fields = ${?SCRIBE_REST_DEFAULT_FIELDS}

Default response shape: nodes, edges, pageInfo, count (comma-separated)

Configurable, default: “nodes,pageInfo,count”

Priority: SCRIBE_REST_DEFAULT_INCLUDE > config

channels.rest.default-include = "nodes,pageInfo,count"
channels.rest.default-include = ${?SCRIBE_REST_DEFAULT_INCLUDE}

Query Parameter Defaults

Applied when the client omits the parameter. Client-provided values override these defaults except for max-limit which always caps. Default page size when no limit/first/last specified (configurable, default: 25)

Priority: SCRIBE_REST_DEFAULT_LIMIT > config

channels.rest.default-limit = 25
channels.rest.default-limit = ${?SCRIBE_REST_DEFAULT_LIMIT}

Default sort order (configurable)

• null (default): database-native order (typically insertion order, not guaranteed stable)
• “cn”: sort by cn ascending
• “-modifyTimestamp,cn”: sort by modifyTimestamp descending, then cn ascending

Priority: SCRIBE_REST_DEFAULT_SORT > config

channels.rest.default-sort = ${?SCRIBE_REST_DEFAULT_SORT}

Enable the REST channel

Priority: SCRIBE_REST_ENABLED > config

channels.rest.enabled = false
channels.rest.enabled = ${?SCRIBE_REST_ENABLED}

HTTP server settings for REST API.

This section inherits all settings from http. Override individual settings as needed.

Maximum entries per request (caps client-provided limit, configurable, default: 1000)

Priority: SCRIBE_REST_MAX_LIMIT > config

channels.rest.max-limit = 1000
channels.rest.max-limit = ${?SCRIBE_REST_MAX_LIMIT}

Socket reference for REST API (Phase 3 wiring). Use a named socket from http.sockets.* or omit for @default. If unset (no env var, key omitted, or value is null), defaults to @default.

Priority: SCRIBE_REST_SOCKET > config

channels.rest.socket = ${?SCRIBE_REST_SOCKET}

OpenAPI UI (Scalar API Reference) configuration

Scalar provides a modern, interactive API documentation UI. By default, assets are bundled with the app (offline-safe, no external network). Settings marked AUTO resolve based on app.mode:

• Dev/test/local: developer-friendly (show tools, enable requests)
• Production/staging: production-safe (hide tools, disable requests)

External asset configuration (CDN override). By default, Scalar assets are bundled with the app (offline-safe). If configured, both url and sri are required. SRI (Subresource Integrity) hash prevents supply-chain attacks.

CDN providers:

• jsDelivr: https://www.jsdelivr.com/package/npm/@scalar/api-reference
• unpkg: https://unpkg.com/browse/@scalar/api-reference/
• cdnjs: https://cdnjs.com/libraries/scalar-api-reference

Bundle path: /dist/browser/standalone.min.js

Subresource Integrity hash for the asset URL.

Example: "sha384-HjTUYHbvChA/watX+X7iQtuhwMhsCYU600qyfXPYC90fYr/2Y/Mg7ybHlvkp+eUW"

Priority: SCRIBE_REST_UI_ASSET_SRI > config

channels.rest.ui.asset.sri = ${?SCRIBE_REST_UI_ASSET_SRI}

CDN URL for Scalar standalone JavaScript bundle.

Example: "https://cdn.jsdelivr.net/npm/@scalar/api-reference@1.43.1/dist/browser/standalone.min.js"

Priority: SCRIBE_REST_UI_ASSET_URL > config

channels.rest.ui.asset.url = ${?SCRIBE_REST_UI_ASSET_URL}

Dark mode: Initial color mode when loading the UI

true = start in dark mode, false = start in light mode

Users can toggle unless hide-dark-mode-toggle is set

Priority: SCRIBE_REST_UI_DARK_MODE > config

channels.rest.ui.dark-mode = false
channels.rest.ui.dark-mode = ${?SCRIBE_REST_UI_DARK_MODE}

Enable OpenAPI UI (Scalar API Reference)

auto = enabled in dev/test, disabled in prod (prod-safe default)

true = always enabled, false = always disabled

Priority: SCRIBE_REST_UI_ENABLED > config

channels.rest.ui.enabled = "auto"
channels.rest.ui.enabled = ${?SCRIBE_REST_UI_ENABLED}

Force dark mode state: Lock the UI to ‘dark’ or ‘light’ mode When set, overrides dark-mode and prevents user toggling Values: ‘dark’, ‘light’, or null (user can toggle)

Priority: SCRIBE_REST_UI_FORCE_DARK_MODE_STATE > config

channels.rest.ui.force-dark-mode-state = ${?SCRIBE_REST_UI_FORCE_DARK_MODE_STATE}

Hide dark mode toggle: Remove the light/dark mode toggle button Useful with force-dark-mode-state to enforce a specific mode

Priority: SCRIBE_REST_UI_HIDE_DARK_MODE_TOGGLE > config

channels.rest.ui.hide-dark-mode-toggle = false
channels.rest.ui.hide-dark-mode-toggle = ${?SCRIBE_REST_UI_HIDE_DARK_MODE_TOGGLE}

Hide test request button: Remove the “Send Request” button Prevents users from making live API calls through the UI

auto = show in dev/test (for testing), hide in prod (security)

Priority: SCRIBE_REST_UI_HIDE_TEST_REQUEST_BUTTON > config

channels.rest.ui.hide-test-request-button = "auto"
channels.rest.ui.hide-test-request-button = ${?SCRIBE_REST_UI_HIDE_TEST_REQUEST_BUTTON}

Layout: Overall layout style of the API reference ‘modern’ = split view with sidebar, ‘classic’ = single column

Priority: SCRIBE_REST_UI_LAYOUT > config

channels.rest.ui.layout = "modern"
channels.rest.ui.layout = ${?SCRIBE_REST_UI_LAYOUT}

Search hotkey: Keyboard shortcut to open search (with Cmd/Ctrl) Common values: ‘k’ (GitHub-style), ’/’ (Vim-style)

Priority: SCRIBE_REST_UI_SEARCH_HOT_KEY > config

channels.rest.ui.search-hot-key = "k"
channels.rest.ui.search-hot-key = ${?SCRIBE_REST_UI_SEARCH_HOT_KEY}

Policy Options (with AUTO mode)

These settings control security-sensitive features and support AUTO mode: true/on/yes - Always enabled (override environment default) false/off/no - Always disabled (override environment default) auto - Environment-aware: enabled in dev/test, disabled in prod Developer tools: Show Scalar’s developer tools panel Exposes request/response details, headers, and debugging info

auto = show in dev/test (for debugging), hide in prod (security)

Priority: SCRIBE_REST_UI_SHOW_DEVELOPER_TOOLS > config

channels.rest.ui.show-developer-tools = "auto"
channels.rest.ui.show-developer-tools = ${?SCRIBE_REST_UI_SHOW_DEVELOPER_TOOLS}

Show sidebar: Display the navigation sidebar with endpoints

true = show sidebar, false = hide for cleaner embedded view

Priority: SCRIBE_REST_UI_SHOW_SIDEBAR > config

channels.rest.ui.show-sidebar = true
channels.rest.ui.show-sidebar = ${?SCRIBE_REST_UI_SHOW_SIDEBAR}

Appearance Options

These settings control the visual appearance of the Scalar UI. Theme: Visual color scheme for the API reference UI Available: alternate, default, moon, purple, solarized, bluePlanet, saturn, kepler, mars, deepSpace, laserwave, none

Priority: SCRIBE_REST_UI_THEME > config

channels.rest.ui.theme = "default"
channels.rest.ui.theme = ${?SCRIBE_REST_UI_THEME}