Backend configuration

Configure the server

Use Inth when you want managed hosting. These options belong to a self-hosted @c15t/backend instance. Browser hosted() options only select how a client connects; they do not configure the backend's policy.

import { defineConfig, policyRulePresets } from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

export default defineConfig({
	database: { dialect: 'postgres', url, schema: 'c15t' },
	basePath: '/api/c15t',
	trustedOrigins: ['https://app.example.com'],
	manifest: { policyRules: [policyRulePresets.europeOptIn()] },
	ipAddress: { tracking: false },
});

The example uses the Europe preset for its matching locations and unknown-location fallback. Add reviewed rules for other locations in policy configuration.

Instance options

defineConfig() checks types and returns the supplied object. It does not load environment variables or run migrations. It deliberately rejects observability; pass logging callbacks when constructing the instance instead.

Manifest options

Browser script routes

The backend serves /c15t.js, /c15t.headless.js and /c15t.iab.js by default, so a self-hosted instance can serve a configured script tag without a separate bundle deployment. Turn them off when you do not use the script tag:

const backend = c15tInstance({ ...config, script: { enabled: false } });

The /c15t.js route serves the hosted bundle with its backend URL already configured. It resolves each visitor's policy through /init. The headless and IAB routes inline the public manifest and resolve it in the browser. Keep secrets out of script.config.

@c15t/backend installs @c15t/browser as a runtime dependency, including its core, UI, IAB, and DevTools dependencies. Disabling the routes removes the HTTP endpoints; it does not remove those packages from the installation. Bundle files load when requested. A missing bundle returns 503.

With c15tInstance({ basePath: '/api/c15t', ... }), a script loaded from /api/c15t/c15t.js calls /api/c15t/init and /api/c15t/subjects. You do not need to repeat the mount path in script.backendURL.

Pass these options under script in the c15tInstance() or defineConfig() options:

The routes share the /manifest cache policy through manifestCache and return ETags for conditional requests. See the endpoint reference and script-tag guide for usage.

Origins, identity and secrets

A trustedOrigins entry matches a hostname on any web scheme. Add a port to pin one, such as localhost:3000. *.example.com matches subdomains, and * allows every origin. CORS controls which browser pages can read responses. It is not authentication and does not prevent a non-browser client from calling a public endpoint. GET /init is open to every origin without credentials, because it returns only public policy data for the request's location; consent saves and subject reads keep the allowlist. Keep API keys, database credentials and signing keys in server environment variables.

A tenantId scopes an instance, not an arbitrary incoming header. Construct the correct tenant instance in trusted application code. Do not choose a tenant from an unchecked browser value.

When several tenants share one database, set requireTenantId: true on every instance. Without it, an instance whose tenant lookup returned undefined starts in the single-tenant scope. It then writes consents with a null tenant, which the tenant that owns them never reads, and nothing reports the problem.

import { c15tInstance, type C15TInstance } from '@c15t/backend';

const url = process.env.DATABASE_URL;
if (!url) throw new Error('Set DATABASE_URL');

// One instance per tenant: each instance owns a connection pool.
const instances = new Map<string, C15TInstance>();

export function instanceFor(tenantId: string | undefined) {
	const key = tenantId ?? '';
	let instance = instances.get(key);
	if (!instance) {
		instance = c15tInstance({
			database: { dialect: 'postgres', url },
			tenantId,
			// Throws here if the tenant lookup returned undefined.
			requireTenantId: true,
		});
		instances.set(key, instance);
	}
	return instance;
}

Subject IDs are chosen by the browser and are unique across the whole database, not per tenant. When a save names a subject ID that another tenant already holds, the backend answers 409 SUBJECT_CONFLICT and writes nothing. The c15t client then generates a new subject ID for that visitor and sends the choice once more.

ipAddress.ipAddressHeaders overrides the ordered headers used to record an IP. Configure the reverse proxy to replace trusted forwarding headers. IP recording and policy location resolution are separate operations.

See HTTP endpoints, request logging and legal-document snapshots.