Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.coralos.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.