Workspace keys

Every workspace receives a public key named Default. Use that workspace key across your Apps. Copy it from Settings → Developer → Public keys, where you can also create, roll or revoke workspace keys. Additional keys are optional; you do not need a separate key for every App.

Public keys can be included in browser code. Build secrets remain server-side. For your first installation, follow onboarding with workspace keys; for infrastructure-managed keys, see the Terraform provider guide.

How requests select an App

A workspace key identifies the workspace. The request supplies the service identity, in this order:

1. x-interfere-service, with optional x-interfere-service-namespace, takes precedence over telemetry resource attributes.
2. Without that header, OTLP exports use service.name and service.namespace. A batch containing several services is split and routed per service.
3. Without a usable identity, the request uses the workspace’s default App. unknown_service never creates an App.

For a named service, an existing service-to-App association wins. Otherwise, a matching live App name or slug is associated with that service. Names match without case sensitivity. If the service is new and no App matches, Interfere can create an App on first sight.

Select Default app in Settings → Developer → Public keys. If the configured default is missing or deleted, routing uses the oldest live App eligible for fallback. If no eligible App exists and the request cannot create one, it is rejected.

Name the service in code

Choose a stable serviceName and use it consistently in the build plugin, browser initialization and server registration. For Next.js:

1import { withInterfere } from "@interfere/next/config";23export default withInterfere({ serviceName: "storefront" }, {});

For Vite:

1import { interfere } from "@interfere/vite/plugin";2import { defineConfig } from "vite";34export default defineConfig({5  plugins: [interfere({ serviceName: "storefront" })],6});

Pass the same serviceName: "storefront" to the framework SDK’s browser init() and server/edge register() when used. The React provider uses the framework SDK’s identity; its props do not name the service. Keep an application-owned OpenTelemetry provider’s service.name aligned too.

The build default is the explicit serviceName option, then OTEL_SERVICE_NAME, then the package name without its scope. Runtime overrides can change that identity, so keep them aligned. SDK config, session, replay and release requests send the identity as x-interfere-service; a runtime serviceNamespace also sends x-interfere-service-namespace.

A build warns when release preflight resolves an App whose slug differs from the inferred service name. An explicit build serviceName or OTEL_SERVICE_NAME suppresses that warning; an unresolved App produces no name warning. The warning does not stop the build.

Name the App in the dashboard

Enter the App name when creating an App, or edit the title on its App page. Open Services to find the service linked to an existing App. Renaming the dashboard title does not rename the SDK’s service or change an existing association.

Before changing a key, copy the existing service name from Services or inspect service.name on a recent span. Changing the service name with a workspace key can select or create another App.

Control automatic creation

Automatic creation is limited to 20 new Apps per request and 50 auto-created Apps per workspace. These limits apply to automatic creation, not the total number of manually configured Apps. Unknown or absent service names do not create Apps.

Turn off Create apps from telemetry in Settings → Developer → Public keys to disable auto_create_apps. When creation is disabled or a budget is exhausted, an unmatched service falls back to the default App. Without an eligible default, the request is rejected.

The per-App explicit_only setting excludes an App from implicit OTLP name matching and default fallback. An explicit x-interfere-service header can match it by slug or name, with x-interfere-service-namespace selecting the service namespace. An existing service association can still select it, and its App key remains usable.

Migrate an App key

App keys, previously called surface keys, are deprecated but still accepted. No removal date has been announced. They stay bound to their App and bypass workspace-key routing.

1. Record the existing service name and keep it explicit in the SDK and build configuration.
2. Replace the public key with the workspace’s Default key. Use INTERFERE_PUBLIC_KEY for Next.js or VITE_INTERFERE_PUBLIC_KEY for Vite.
3. Build and send telemetry, then check that the expected App receives it and that releases resolve to that App.
4. Keep the old key until every deployment using it has migrated; then revoke it if it is no longer needed.

Rolling a workspace key can use a grace period; the default is seven days. Revoking a workspace key affects every App still using it. Update all deployments before retiring a shared key.