Langfuse headless initialization and instance management API

The startup sequence is what turns an empty Langfuse database into a usable instance without a manual setup step. Langfuse reads the LANGFUSE_INIT_* variables when the web container starts and creates the first organization, project, API keys and user if those objects are missing. The order matters because each object depends on the one before it. A project or user cannot be initialized without an organization, so the organization must be defined in the same configuration. Keep the variable set in one file that a reviewer can read from top to bottom, and confirm that every dependent object has its parent defined before the first deployment runs.

Restart behavior is where most provisioning mistakes happen. The variables only create objects that do not already exist, so a restart, a rolling update or a redeployment does not recreate the organization, project, user or keys. Existing objects stay as they are. Teams often assume that changing a value in the manifest will rename a project or replace its keys, and by default it will not. Before you change any initialization value after go-live, confirm on the headless initialization page how each variable behaves when its object already exists, and whether a new value is applied or ignored. Test that behavior on a staging instance first.

The dependency chain also shapes access. The organization sits at the top, projects belong to it, and the initial user is created within that structure. LANGFUSE_DEFAULT_ORG_ID and LANGFUSE_DEFAULT_PROJECT_ID place each new sign-in into a named organization and project, with roles set by LANGFUSE_DEFAULT_ORG_ROLE and LANGFUSE_DEFAULT_PROJECT_ROLE. The documented default role is VIEWER. Choose these roles with your access model in mind, because a broad default gives every new user read access to traces that may contain personal data. Confirm the exact variable names and accepted role values on the headless initialization page before you write them into your configuration.

Generated API keys need a controlled handoff. The keys created at startup authenticate your deployment pipelines and applications to a specific project, so they should go from the instance straight into your secret store and stay out of shared documents, chat threads and build logs. Map each key to the one pipeline that uses it, name it so the consumer is obvious, and grant read access in the secret store only to that pipeline. Record which key was issued at which deployment so that rotation later is a planned task. Before the first production start, ask your team or your provider to confirm where key values can appear in container output, because default log collection may capture startup messages.

The Langfuse Instance Management API is the point where organization and key administration moves from people clicking through an interface to code that runs on a schedule or in response to an event. It is an Enterprise Edition interface that creates, updates and deletes organizations and organization API keys. Requests authenticate with a bearer token, which is the ADMIN_API_KEY value set on your self-hosted instance. Because the API requires an Enterprise license key and is not available on Langfuse Cloud, it applies only to a deployment you run. Treat ADMIN_API_KEY as a highly privileged credential, since anyone holding it can create organizations and issue keys. Store it in your secrets manager, restrict who can read it, and keep it out of CI logs and shell history.

Teams usually need the API for two reasons. The first is an automated organization lifecycle across many business units. When each unit needs its own organization, creating it at onboarding and deleting it at retirement is easier to control from an HR or service catalog workflow than from manual steps. The second is scripted key rotation. A pipeline can issue new organization API keys, write them to the secret stores of the consuming services, and revoke the old keys on a defined schedule. The LANGFUSE_INIT variables cannot cover either case, because they create resources only at first startup when those resources do not yet exist. For ongoing change, you need the API or a manual process.

The API is unnecessary when the deployment has a single organization with a small number of projects, and when key changes are rare enough that a named administrator can perform them with a short, documented procedure. It is also unnecessary if you do not hold an Enterprise license key, because the API will not be available to you. Automation adds a privileged credential, a service to monitor and a code base that needs review and testing. Before committing to it, ask whether organization changes and key rotations are recurring and high in volume. If they are not, a documented manual runbook may carry less risk and less maintenance.

The API does not cover every administrative action. The supported scope described here is creating, updating and deleting organizations and organization API keys. Any other admin task, such as changes outside those two objects, may require a different route or a manual step, and you should not assume an endpoint exists for it. Before design begins, list every admin action your automation must perform and check each one against the Instance Management API documentation for the Langfuse version you run. Record the endpoints you confirmed and the steps you could not automate in the design record. Any unsupported step will otherwise fall back to a person holding admin access, which weakens the control you were trying to build.

The default roles decide what every new account can do the moment it first signs in. In a self-hosted Langfuse, LANGFUSE_DEFAULT_ORG_ID and LANGFUSE_DEFAULT_PROJECT_ID add each new user to a chosen organization and project, while LANGFUSE_DEFAULT_ORG_ROLE and LANGFUSE_DEFAULT_PROJECT_ROLE set the role they receive in each. Both role variables default to VIEWER, so if you set the IDs and leave the roles alone, new users join with read-only access. Before the first user signs in, confirm that the IDs match the organization and project created by your LANGFUSE_INIT values. A mismatch would place new users in a place you did not intend, and it is much easier to catch during provisioning than afterward.

Set each default to the least privileged role that still lets people do their work, and grant anything higher deliberately. Viewer suits stakeholders who only need to read traces, dashboards and scores. Engineers who create prompts, manage datasets or change project settings should be promoted one at a time, by an administrator who records why. Avoid setting an elevated role as the default to speed up onboarding, because every later sign-in then inherits that access without review. Write down which roles new users receive, who may approve a promotion, and how access is reduced when someone changes teams.

Project-level RBAC roles are listed in Langfuse's license key documentation as an Enterprise feature. Treat the project role default as meaningful only after you confirm which roles your edition exposes and whether your license key enables them. Do not assume that the open source edition supports the same role names or the same project-level controls. Ask Langfuse to confirm the available roles for your version, then test them in a non-production instance by creating a test user, signing in and checking what the interface and API allow at each level. If your edition lacks these roles, plan access around organization membership and project boundaries instead, and document that limit for your auditors.

Record the chosen defaults in the same deployment repository as your other provisioning values, and review them whenever you change SSO settings or domain rules. Changing an environment variable generally affects accounts created after the change, so existing users need a separate access review. Confirm with Langfuse how default role changes apply to existing accounts in your version before you rely on that behavior. A short checklist works well: the IDs match the initialized objects, the roles are the least privileged that work, the edition supports the chosen roles, and a test sign-in in staging produces the expected access.

Headless initialization creates the first organization, project, API keys and user when the instance starts, but it does not govern how people sign in afterward. Day-to-day access belongs to single sign-on. Self-hosted Langfuse connects to identity providers through Auth.js providers such as Entra ID, Okta, Keycloak or generic OIDC. Treat the two as separate layers in your design document: the LANGFUSE_INIT variables establish a known starting state, and the SSO configuration decides who can sign in to that state later. Mixing them up is the most common source of confusion when an instance is redeployed.

Before you write any configuration, list every identity that the initialization variables will create and label each one as bootstrap-only or SSO-managed. The bootstrap user is usually a named administrator kept for setup and for recovery if the identity provider is unavailable. Record who holds its credentials, where those credentials are stored, and how they are rotated. Then decide what role new SSO users receive. LANGFUSE_DEFAULT_ORG_ROLE and LANGFUSE_DEFAULT_PROJECT_ROLE both default to VIEWER, so confirm that this is the level you want for newly provisioned staff and document any exception.

Once SSO works, you can disable password sign-in or enforce SSO for specific email domains. Sequence the change deliberately. First, complete an SSO sign-in with a non-bootstrap administrator in a staging instance. Second, confirm that the bootstrap account still works under the setting you plan to apply. Third, enable domain enforcement and test with an account from each domain you expect, including contractors or partner addresses that may not follow your primary domain. A domain rule that blocks a valid user is easy to create and can be hard to notice until a team needs access during an incident.

If you plan to automate user lifecycle changes such as joiners, movers and leavers, confirm coverage before you design the pipeline. Langfuse lists the organization management API with SCIM, and the instance management API, as features that require an Enterprise license key. The instance management API is Enterprise only and is not available on Langfuse Cloud. Ask Langfuse in writing which of these endpoints and SCIM behaviors your license tier includes, including deprovisioning and role mapping. If coverage is partial, plan manual offboarding steps or a scheduled reconciliation job, and assign an owner for each step.