Hosted API
The Next.js control plane that owns experiment lifecycle, auth, manifests, audit events, aggregate queries, and org API keys.
apps/api is the hosted control plane. It runs as a Next.js Node application in
the combined production Databricks App and through OpenNext in Cloudflare-native
staging. Both shapes keep authentication, organization authorization and
product endpoints in the same API boundary.
The externally deployed API base is /api. Protocol paths are relative to
that base and start with /v1, so an ApiClient configured with
https://studio.example.com/api calls full routes under
https://studio.example.com/api/v1/.... fx login performs this normalization
for a bare Studio URL.
Public API groups
/api/auth/*— Better Auth./api/v1/tenants/me— current organization/member context./api/v1/organizations/generate-slug— authenticated org slug generation for onboarding./api/v1/organizations/resolve— authenticated org slug resolution for Studio URL-scoped routes./api/v1/orgs/{orgId}/experiments/*— experiments and actions./api/v1/orgs/{orgId}/manifests/*— keys and publishing./api/v1/orgs/{orgId}/audit— audit events./api/v1/orgs/{orgId}/api-keys— org API key list/create./api/v1/orgs/{orgId}/api-keys/{keyId}— org API key revoke./.well-known/jwks/{orgId}— manifest verification keys.
Authentication
Handlers are generated around endpoint definitions from packages/api-protocol. Each route gets auth resolution, org role checks, zod validation, and consistent JSON errors.
Supported auth modes:
- Browser sessions from Better Auth cookies for Studio.
- Org API keys using
x-api-key: fx_key_...for CLI and automation. Keeping hosted keys separate from OAuth bearer tokens prevents an upstream identity gateway from consuming the wrong credential.
API keys are created in Studio under /app/{orgSlug}/settings. The key is shown once, stored hashed in Postgres, and can be revoked from Studio. Successful API key usage updates lastUsedAt.