Skip to main content
This page explains how authentication and request signing work in Coral Server, and how agent secrets are handled at runtime.

​
Authentication keys (server API)

  • Source of truth: AuthConfig.kt
  • Configuration source: config.toml (via Hoplite in ConfigModule.kt)
Coral Server protects its REST/WebSocket APIs with bearer tokens. 
# config.toml (excerpt)
[auth]
# A list of accepted bearer tokens for server APIs
keys = ["dev-token-123", "another-token"]
Use one of these tokens in the Authorization: Bearer ... header when calling APIs such as /api/v1/local/session or /api/v1/registry.
Keep tokens secret. Do not commit them to source control.

​
Request signing for webhooks and custom tools

  • Source of truth: NetworkConfig.kt (webhookSecret, customToolSecret), LocalSessionManager.handleSessionClose, GraphAgentToolTransport.Http, and HttpSignatureUtils.kt
Coral signs JSON payloads for server‑initiated webhooks (e.g., sessionEnd) and for HTTP‑based custom tool requests. Verify signatures on your server to prevent spoofing. 
# config.toml (excerpt)
[network]
# Used to sign webhook payloads (e.g., sessionEnd)
webhookSecret = "CHANGE-ME-32-CHARS"

# Used to sign custom tool callouts to your HTTP endpoints
customToolSecret = "CHANGE-ME-ANOTHER-SECRET"
Verification pattern (default header and algorithm): 
X-Coral-Signature: HMAC-SHA256(webhookSecret, rawBody)
The default signature header is X-Coral-Signature. For HTTP custom tools, you may override the header name via the transport’s signatureHeader option; otherwise the default is used.
See the examples in Integrating with your app. Always verify request signatures in production.

​
SessionAgentSecret (agent → server)

  • Source of truth: SessionAgent.kt and LocalSessionManager.issueAgentSecret
For each agent instance in a session, Coral issues a unique SessionAgentSecret. This secret authenticates the agent when connecting to the MCP server (SSE/WebSocket). Properties:
  • Random per agent instance
  • Only valid for the lifetime of the session
  • Revoked automatically when the session ends
Best practices for agent authors:
  • Read CORAL_AGENT_SECRET from the environment provided by the orchestrator
  • Only use it to authenticate your MCP transport
  • Do not log or transmit the secret elsewhere
Related env vars (set by the orchestrator):
VariablePurpose
CORAL_CONNECTION_URLMCP transport URL to connect to
CORAL_AGENT_IDUnique name of this agent instance in the session
CORAL_AGENT_SECRETSecret used to authenticate to Coral’s MCP endpoints
CORAL_SESSION_IDSession identifier
CORAL_API_URLCoral Server REST API base URL

​
CORS and CSRF considerations

The server’s CORS policy is controlled by NetworkConfig.allowAnyHost (default: false). 
[network]
allowAnyHost = false # set true only for local development
Set allowAnyHost = false in production and explicitly configure your reverse proxy/frontend to call Coral from trusted origins.

​
Checklist

  • Use strong random auth.keys, rotate regularly
  • Set webhookSecret and customToolSecret to strong values
  • Verify webhook signatures in your app
  • Never log CORAL_AGENT_SECRET
  • Keep allowAnyHost = false in production
TODO: Add concrete code samples (Node/Go/Python) for verifying webhook signatures.