Skip to content

Cratis Chronicle external-service connections

An External Service in Cratis Chronicle is a named HTTP or database connection owned by an event store. Configure one before defining an API capture so the capture can refer to a name instead of carrying the service’s URL and authentication.

When several captures read the same API, they can reference one External Service. The service holds the base URL, credentials, and headers; each capture chooses its route and polling interval. Register that connection as CustomersApi, for example, then reference it with api CustomersApi without copying its authentication credentials into each declaration.

Choose the endpoint type for the system you want to connect to. Each External Service has one endpoint:

Type Connection settings Used to create
HTTP Base URL, authorization (None / Basic / Bearer / OAuth), and headers An HTTP client target
MSSQL Host, port, database, username, password, and options A Microsoft SQL Server connection string
PostgreSQL Host, port, database, username, password, and options A PostgreSQL connection string

API captures require an HTTP endpoint. Registering a database connection does not make it an API-polling source. For database endpoints, Chronicle builds the connection string through a provider-specific IFormDatabaseConnectionString formatter, discovered by convention.

For a database endpoint, the connection string is built from the configured fields:

  • MSSQL → Server=<host>[,<port>];Database=<db>;User Id=<user>;Password=<pw>;<options...>
  • PostgreSQL → Host=<host>;[Port=<port>;]Database=<db>;Username=<user>;Password=<pw>;<options...>

When the port is left unspecified (0), the provider default is used and the port is omitted from the connection string.

In the Workbench, open the event store that will use the connection and go to General → External Services. Add a service, give it a name, and choose its endpoint type.

For HTTP, enter the base URL and choose an authorization type from the table below. For MSSQL or PostgreSQL, enter the host, database, and any required username and password. The port is optional. After adding the service, confirm its name and endpoint in the service list; you can also view details or remove a selected service there.

Passwords, bearer tokens, and OAuth client secrets are write-only in the Workbench: the read model used to list services does not return those credential fields. Configured headers and database provider options are included in that read model.

To register connections from application code, follow Registering External Services from code in the .NET client docs. Use that registration API for additional HTTP headers or database provider options; the Workbench form does not expose those fields.

Choose the authorization type expected by the API:

Authorization type What to supply How Chronicle authenticates
None No authorization credentials No authorization header is added by this setting
Basic Username and password Sends an HTTP Basic authorization header
Bearer Access token Sends the supplied token in a Bearer authorization header
OAuth Authority, client ID, client secret, and optional scope Discovers the token endpoint from the authority and requests a token using the client-credentials grant

OAuth uses the application’s credentials, without an interactive user sign-in. Its discovery and token requests follow the HTTP capture destination policy below, so include the identity and token hosts when configuring host approvals.

Before polling an HTTP service, configure which destinations the Kernel may call. HTTP captures use the ExternalServices destination policy, independently of Webhooks: approving a webhook host does not approve a capture source or its OAuth hosts.

Put the section at the top level of chronicle.json:

{
"externalServices": {
"validation": "BlockLocalAddresses",
"allowedHosts": ["api.example.com"],
"eventStoreAllowedHosts": {
"orders": ["orders-api.internal"]
}
}
}

Validation defaults to Warn in Development builds and BlockLocalAddresses otherwise. Choose a mode for your deployment:

Mode Behavior
Warn Reports policy violations without blocking requests, except for unapproved cloud metadata addresses
BlockLocalAddresses Blocks unapproved loopback (including mapped IPv4), IPv4 link-local 169.254/16, IPv4 unspecified 0/8, IPv6 link-local fe80::/10, and IPv6 unspecified ::; warns about HTTP, missing host approval, and other private or special destinations
BlockPrivateAddresses Also blocks other unapproved private or special addresses
Enforce Blocks every policy violation, including HTTP and missing host approval

Cloud metadata addresses require explicit host approval in every mode. Never approve metadata hosts in normal deployments. In the Development runtime environment, loopback and host.docker.internal have a development-host exception to host and address restrictions. HTTP is permitted for loopback in that environment; other hosts require AllowInsecureHttp to satisfy the HTTPS check. That setting defaults to false and is ignored outside Development.

AllowedHosts accepts exact hosts and wildcard subdomains such as *.example.com; the wildcard does not match the apex domain example.com. An EventStoreAllowedHosts entry replaces the global list, even when the entry is empty. In the example above, the orders store uses only orders-api.internal as its approved host. Add any required OAuth hosts to that store’s list too.

Explicit approval permits a host’s private addresses but does not waive the HTTPS check. Environment variable names start with Cratis__Chronicle__ExternalServices__, for example Cratis__Chronicle__ExternalServices__Validation.

Every capture request carries its event store. A route resolves against the External Service URL and must stay on the same origin: the same scheme, host, and port. Chronicle refuses a route to another origin before sending the request, keeping the service’s authentication and headers on that service.

Redirects and system proxies are disabled, and DNS is validated when each connection opens. Requests to explicitly approved hosts close their connections after each request, even if the host currently resolves publicly. This prevents one event store’s approval from being reused by another. Unapproved public destinations retain connection pooling in modes that permit them.

The policy covers HTTP capture polling and its OAuth discovery and token requests, not database endpoints. Before upgrading a deployment with local capture APIs, explicitly approve trusted hosts or select Warn as a migration setting. Review other private-network hosts before choosing BlockPrivateAddresses or Enforce. Use the Kernel options reference to configure these settings.

Once the HTTP service is registered and its destinations are permitted, reference its name in the capture’s API source. This excerpt uses CustomersApi for the connection and authentication, then selects /customers as the route to poll every five minutes:

capture Customers
source api
api CustomersApi # references the "CustomersApi" External Service
route /customers
poll 5m
key customerId
...

Continue with Capture Declaration Language to add append rules that define the events to emit when source data changes. Registering the External Service alone does not create or start a capture.