API Key Management#

Overview#

Langfuse uses project-scoped API key pairs to authenticate all SDK and API interactions. Each project has a Public Key (pk-lf-…) and a Secret Key (sk-lf-…), created and managed via Project → Settings in the UI. Keys are automatically generated when a new project is created. 1

The canonical environment variables for SDK initialization are 2:

useLangfuseEnvCode generates this three-line snippet for copy-paste into the UI and CLI flows.

Authentication Mechanisms#

Basic Auth (primary)#

The public API verifies credentials via HTTP Basic Authentication:

• Username: Public Key
• Password: Secret Key
• Credentials are Base64-encoded: Authorization: Basic base64(pk-lf-...:sk-lf-...)

Verification flow in ApiAuthService.verifyAuthHeaderAndReturnScope:

1. Hash the provided secret key with a server-side SHA hash using SALT.
2. Look up the hash in Redis (cache-hit path) or fall back to Postgres.
3. If only a bcrypt hash exists (legacy keys), verify via verifySecretKey and upgrade to the fast SHA hash on success. 3
4. Return a scope object containing projectId, orgId, plan, rate-limit overrides, and accessLevel.

Bearer Auth (limited scope)#

Passing only the Public Key as a Bearer token (Authorization: Bearer pk-lf-…) is supported but grants only scores-level access. Organization-scoped keys are explicitly rejected on this path. 4

Key Scopes#

Keys carry an ApiKeyScope — either PROJECT or ORGANIZATION — stored in the ApiKey database record. 5

• Project-scoped: standard key pair; tied to one project; required for Basic Auth against the MCP server. 6
• Organization-scoped: org-level access; cannot be used with Bearer auth. 7

Multi-project access from a single session is not currently supported. 6

Redis Caching#

API key lookups are cached in Redis to reduce Postgres load. Caching is controlled by two env vars 8:

• LANGFUSE_CACHE_API_KEY_ENABLED=true — enables Redis caching
• LANGFUSE_CACHE_API_KEY_TTL_SECONDS — sets the TTL on cached entries

Cache invalidation methods (invalidateCachedApiKeys, invalidateCachedOrgApiKeys, invalidateCachedProjectApiKeys) are triggered when keys are deleted or when organization/project membership changes. 9

CLI & Agent Authentication#

The Langfuse CLI (npx langfuse-cli) wraps the full REST API and authenticates using the same three environment variables. 10

The authenticated MCP server (/api/public/mcp) requires Basic Auth with a project key pair: 10

{
  "mcpServers": {
    "langfuse-cloud": {
      "url": "https://cloud.langfuse.com/api/public/mcp",
      "transport": "streamableHttp",
      "headers": { "Authorization": "Basic <base64(pk-lf-...:sk-lf-...)>" }
    }
  }
}

The public Docs MCP server (/api/mcp) requires no authentication. 10

Security Considerations & Roadmap#

Risks of static keys in enterprise deployments#

• Long-lived static tokens are a common credential-theft target.
• Keys are project-scoped, not user-scoped — audit logs attribute actions to the key, not individual users.
• In multi-agent or multi-team environments, key sprawl and manual rotation become operational liabilities. 11

Self-hosted hardening#

• Keys are stored hashed: bcrypt for legacy keys; SHA + SALT for fast-hash keys. The SALT env var must be set with ≥256 bits of entropy.
• Set LANGFUSE_CSP_ENFORCE_HTTPS=true to prevent key transmission over plain HTTP.
• Store keys in environment variables or a secrets manager; never hardcode them.

Planned: Fine-grained API keys & OIDC#

A Langfuse maintainer has confirmed that fine-grained API keys are a high-priority roadmap item, and OIDC/OAuth2 authentication for the MCP server is planned to follow. Until that work ships, the recommended enterprise workaround is deploying an OAuth2 reverse proxy (e.g. OAuth2 Proxy, Pomerium) in front of the MCP endpoint to handle SSO and inject Basic Auth headers. 11

Key Source Files#