Principle:Langfuse Langfuse API Authentication and Rate Limiting

Knowledge Sources	Langfuse
Domains	API Security, Trace Ingestion
Last Updated	2026-02-14 00:00 GMT

Overview

API authentication and rate limiting is the practice of verifying the identity of API callers through credential-based schemes and constraining the frequency of their requests to protect backend resources.

Description

In any public-facing data ingestion pipeline, the very first step must establish that the caller is who they claim to be and that they have permission to write data into a specific project scope. Without this gate, the system is vulnerable to unauthorized data injection, data corruption, and denial-of-service attacks.

Langfuse addresses this requirement through a layered approach:

1. Credential Verification: Every inbound HTTP request to the public API must carry an Authorization header using the HTTP Basic authentication scheme. The credentials are a base64-encoded pair of publicKey:secretKey. These keys are project-scoped, meaning each key pair maps to exactly one project, one organization, and one billing plan. A secondary authentication path using an Admin API Key (Bearer token) is available for self-hosted instances performing administrative operations.

1. Rate Limiting: Once authenticated, the request passes through a rate limiter that operates per-project and per-resource bucket. The rate limit service checks whether the project has exceeded its allowed request rate for the given resource type (e.g., public-api, ingestion). Projects on different billing plans may have different rate limit ceilings, and per-project overrides can be configured.

1. Schema Validation: After authentication and rate limiting, request query parameters and body payloads are validated against Zod v4 schemas. This prevents malformed data from propagating deeper into the pipeline.

1. Observability Context Propagation: The authenticated request context (project ID, organization ID) is injected into OpenTelemetry spans so that downstream processing stages can correlate telemetry data back to the originating API call.

This principle applies universally to all public API endpoints in Langfuse, not only to the ingestion pipeline. The pattern is implemented as a higher-order function that wraps any Next.js API handler, enforcing the above checks before the handler executes.

Usage

Apply this principle whenever:

• Designing a new public API endpoint that must be scoped to a project.
• Extending the ingestion pipeline with additional event types that arrive over HTTP.
• Implementing admin-level operations on self-hosted deployments where a separate authentication mechanism is needed.
• Configuring rate limits per project or per billing plan to prevent abuse.

Theoretical Basis

The authentication and rate limiting mechanism follows a chain-of-responsibility pattern, where each stage in the pipeline either passes the request forward or terminates it with an appropriate HTTP error response.

Authentication Flow

1. Extract Authorization header from the HTTP request.
2. If the header starts with "Bearer " and admin auth is allowed:
   a. Verify ADMIN_API_KEY matches using timing-safe comparison.
   b. Verify x-langfuse-admin-api-key header matches (redundancy check).
   c. Look up the project specified by x-langfuse-project-id.
   d. Return auth scope: { projectId, orgId, accessLevel: "project" }.
3. Otherwise, perform Basic Auth:
   a. Decode base64(publicKey:secretKey) from the Authorization header.
   b. Look up the API key pair in the database (with Redis caching).
   c. Verify the secret key matches.
   d. Verify the access level is "project" (not organization-level).
   e. Return auth scope: { projectId, orgId, plan, rateLimitOverrides }.
4. If any step fails, return HTTP 401 Unauthorized.

Rate Limiting Flow

1. Receive the authenticated scope and the rate limit resource identifier.
2. Look up the per-project rate limit configuration (base plan limits + overrides).
3. Check the current request count against the allowed rate for the resource.
4. If the rate is exceeded:
   a. Return HTTP 429 Too Many Requests with Retry-After headers.
5. If the rate is within bounds:
   a. Increment the request counter.
   b. Continue to schema validation.

Schema Validation Flow

1. If a query schema is defined, parse req.query through the Zod schema.
2. If a body schema is defined, parse req.body through the Zod schema.
3. If parsing fails, return HTTP 400 Bad Request with validation error details.
4. If parsing succeeds, pass validated data to the handler function.

The entire chain runs within an OpenTelemetry context that carries the project ID and request headers, ensuring that all downstream spans and metrics are correctly attributed.

Security Considerations

• Timing-safe comparison: Admin API key verification uses crypto.timingSafeEqual to prevent timing attacks that could leak key material through response time analysis.
• Dual-header verification: Admin authentication requires the key in both the Bearer token and a custom header for defense-in-depth.
• Cloud restriction: Admin API key authentication is explicitly disabled on Langfuse Cloud, limiting it to self-hosted instances where the operator controls the infrastructure.

Related Pages

Implemented By

• Implementation:Langfuse_Langfuse_CreateAuthedProjectAPIRoute