CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/maven-com-langfuse--langfuse-java

Java client for the Langfuse API providing access to observability and analytics features for LLM applications

Overview
Eval results
Files

projects-organizations.mddocs/

Projects and Organizations

The Projects and Organizations APIs provide management of projects, API keys, and organization/project memberships. Most organization-level operations require an organization-scoped API key.

Capabilities

ProjectsClient

Client for managing projects and API keys.

/**
 * Get projects associated with the API key
 *
 * @param requestOptions Optional request configuration
 */
Projects get();
Projects get(RequestOptions requestOptions);

/**
 * Create a new project
 * Requires organization-scoped API key
 *
 * @param request Project definition
 * @param requestOptions Optional request configuration
 */
Project create(CreateProjectRequest request);
Project create(CreateProjectRequest request, RequestOptions requestOptions);

/**
 * Update a project by ID
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param request Update data
 * @param requestOptions Optional request configuration
 */
Project update(String projectId, UpdateProjectRequest request);
Project update(String projectId, UpdateProjectRequest request, RequestOptions requestOptions);

/**
 * Delete a project by ID (asynchronous operation)
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param requestOptions Optional request configuration
 */
ProjectDeletionResponse delete(String projectId);
ProjectDeletionResponse delete(String projectId, RequestOptions requestOptions);

/**
 * Get all API keys for a project
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param requestOptions Optional request configuration
 */
ApiKeyList getApiKeys(String projectId);
ApiKeyList getApiKeys(String projectId, RequestOptions requestOptions);

/**
 * Create a new API key for a project
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param request API key configuration
 * @param requestOptions Optional request configuration
 */
ApiKeyResponse createApiKey(String projectId);
ApiKeyResponse createApiKey(String projectId, CreateApiKeyRequest request);
ApiKeyResponse createApiKey(String projectId, CreateApiKeyRequest request, RequestOptions requestOptions);

/**
 * Delete an API key for a project
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param apiKeyId API key ID
 * @param requestOptions Optional request configuration
 */
ApiKeyDeletionResponse deleteApiKey(String projectId, String apiKeyId);
ApiKeyDeletionResponse deleteApiKey(String projectId, String apiKeyId, RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.projects.types.*;
import com.langfuse.client.resources.projects.requests.CreateProjectRequest;
import java.time.OffsetDateTime;

// Note: Use organization-scoped API key for most operations
LangfuseClient client = LangfuseClient.builder()
    .url("https://cloud.langfuse.com")
    .credentials("org-pk-...", "org-sk-...")  // Organization-scoped key
    .build();

// Get projects
Projects projects = client.projects().get();
for (Project project : projects.getData()) {
    System.out.println("Project: " + project.getName());
}

// Create a project - Note: Staged builder requires name() -> retention() (required)
CreateProjectRequest projectRequest = CreateProjectRequest.builder()
    .name("New Project")  // Required first: project name
    .retention(0)  // Required second: retention days (0 or >= 3)
    .build();

Project newProject = client.projects().create(projectRequest);

// Update a project
UpdateProjectRequest updateRequest = UpdateProjectRequest.builder()
    .name("Updated Project Name")
    .build();

Project updated = client.projects().update(newProject.getId(), updateRequest);

// Get API keys for a project
ApiKeyList keys = client.projects().getApiKeys(newProject.getId());
for (ApiKeySummary key : keys.getData()) {
    System.out.println("Key: " + key.getPublicKey());
    key.getNote().ifPresent(note -> System.out.println("Note: " + note));
}

// Create an API key
CreateApiKeyRequest keyRequest = CreateApiKeyRequest.builder()
    .note("Production Key")
    .build();

ApiKeyResponse apiKey = client.projects().createApiKey(newProject.getId(), keyRequest);
System.out.println("Secret key (save this!): " + apiKey.getSecretKey());
System.out.println("Public key: " + apiKey.getPublicKey());

// Delete an API key
ApiKeyDeletionResponse deleteResp = client.projects()
    .deleteApiKey(newProject.getId(), apiKey.getId());

// Delete a project
ProjectDeletionResponse projectDelete = client.projects()
    .delete(newProject.getId());

OrganizationsClient

Client for managing organization and project memberships (requires organization-scoped API key).

/**
 * Get all memberships for the organization
 * Requires organization-scoped API key
 *
 * @param requestOptions Optional request configuration
 */
MembershipsResponse getOrganizationMemberships();
MembershipsResponse getOrganizationMemberships(RequestOptions requestOptions);

/**
 * Create or update an organization membership
 * Requires organization-scoped API key
 *
 * @param request Membership definition
 * @param requestOptions Optional request configuration
 */
MembershipResponse updateOrganizationMembership(MembershipRequest request);
MembershipResponse updateOrganizationMembership(MembershipRequest request, RequestOptions requestOptions);

/**
 * Get all memberships for a specific project
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param requestOptions Optional request configuration
 */
MembershipsResponse getProjectMemberships(String projectId);
MembershipsResponse getProjectMemberships(String projectId, RequestOptions requestOptions);

/**
 * Create or update a project membership
 * Requires organization-scoped API key
 *
 * @param projectId Project ID
 * @param request Membership definition
 * @param requestOptions Optional request configuration
 */
MembershipResponse updateProjectMembership(String projectId, MembershipRequest request);
MembershipResponse updateProjectMembership(String projectId, MembershipRequest request, RequestOptions requestOptions);

/**
 * Get all projects for the organization
 * Requires organization-scoped API key
 *
 * @param requestOptions Optional request configuration
 */
OrganizationProjectsResponse getOrganizationProjects();
OrganizationProjectsResponse getOrganizationProjects(RequestOptions requestOptions);

Usage Examples:

import com.langfuse.client.resources.organizations.types.*;

// Get organization memberships
MembershipsResponse orgMembers = client.organizations()
    .getOrganizationMemberships();

for (MembershipResponse member : orgMembers.getData()) {
    System.out.println(member.getEmail() + " - " + member.getRole());
}

// Add a user to the organization
MembershipRequest memberRequest = MembershipRequest.builder()
    .email("user@example.com")
    .role(MembershipRole.MEMBER)
    .build();

MembershipResponse newMember = client.organizations()
    .updateOrganizationMembership(memberRequest);

// Get project memberships
MembershipsResponse projectMembers = client.organizations()
    .getProjectMemberships("project-123");

// Add a user to a project
MembershipRequest projectMemberRequest = MembershipRequest.builder()
    .email("user@example.com")
    .role(MembershipRole.ADMIN)
    .build();

MembershipResponse projectMember = client.organizations()
    .updateProjectMembership("project-123", projectMemberRequest);

// Get all organization projects
OrganizationProjectsResponse orgProjects = client.organizations()
    .getOrganizationProjects();

for (OrganizationProject project : orgProjects.getData()) {
    System.out.println(project.getName() + " - Role: " + project.getRole());
}

Request Types

CreateProjectRequest

/**
 * Request for creating a project
 *
 * Staged Builder Pattern (required order):
 * 1. name(String) - Project name (required first)
 * 2. retention(int) - Data retention days (required second)
 *    Must be 0 or at least 3 days
 * 3. metadata(Map<String, Object>) - Optional metadata
 * 4. build() - Build the request
 */
public final class CreateProjectRequest {
    String getName();  // Project name
    Optional<Map<String, Object>> getMetadata();  // Optional metadata
    int getRetention();  // Data retention days (required)

    static NameStage builder();  // Returns staged builder starting with name()
}

UpdateProjectRequest

/**
 * Request for updating a project
 */
public final class UpdateProjectRequest {
    String getName();  // New project name

    static Builder builder();
}

CreateApiKeyRequest

/**
 * Request for creating an API key
 */
public final class CreateApiKeyRequest {
    Optional<String> getNote();  // Optional note for the API key

    static Builder builder();
}

MembershipRequest

/**
 * Request for creating or updating a membership
 */
public final class MembershipRequest {
    String getEmail();         // User email
    MembershipRole getRole();  // OWNER, ADMIN, MEMBER, VIEWER

    static Builder builder();
}

Response Types

Project

/**
 * Project definition
 */
public final class Project {
    String getId();
    String getName();
    Map<String, Object> getMetadata();       // Metadata for the project
    Optional<Integer> getRetentionDays();    // Number of days to retain data

    static Builder builder();
}

Projects

/**
 * List of projects
 */
public final class Projects {
    List<Project> getData();

    static Builder builder();
}

ProjectDeletionResponse

/**
 * Response after deleting a project
 */
public final class ProjectDeletionResponse {
    boolean getSuccess();

    static Builder builder();
}

ApiKeySummary

/**
 * Summary information about an API key
 * Note: Secret key is never returned in summaries
 */
public final class ApiKeySummary {
    String getId();
    OffsetDateTime getCreatedAt();
    Optional<OffsetDateTime> getExpiresAt();
    Optional<OffsetDateTime> getLastUsedAt();
    Optional<String> getNote();          // Optional note for the key
    String getPublicKey();
    String getDisplaySecretKey();        // Partially masked secret key

    static Builder builder();
}

ApiKeyList

/**
 * List of API keys
 */
public final class ApiKeyList {
    List<ApiKeySummary> getData();

    static Builder builder();
}

ApiKeyResponse

/**
 * Response after creating an API key
 * Contains both public and secret keys
 * WARNING: Secret key is only shown once - save it immediately!
 */
public final class ApiKeyResponse {
    String getId();
    OffsetDateTime getCreatedAt();
    String getPublicKey();           // Public key
    String getSecretKey();           // Secret key (only shown once!)
    String getDisplaySecretKey();    // Partially masked secret key
    Optional<String> getNote();      // Optional note for the key

    static Builder builder();
}

ApiKeyDeletionResponse

/**
 * Response after deleting an API key
 */
public final class ApiKeyDeletionResponse {
    boolean getSuccess();

    static Builder builder();
}

MembershipResponse

/**
 * Membership information
 */
public final class MembershipResponse {
    String getId();
    String getEmail();
    MembershipRole getRole();
    Optional<String> getName();  // User display name

    static Builder builder();
}

MembershipsResponse

/**
 * List of memberships
 */
public final class MembershipsResponse {
    List<MembershipResponse> getData();

    static Builder builder();
}

OrganizationProject

/**
 * Project with user's role
 */
public final class OrganizationProject {
    String getId();
    String getName();
    MembershipRole getRole();  // User's role in the project

    static Builder builder();
}

OrganizationProjectsResponse

/**
 * List of organization projects
 */
public final class OrganizationProjectsResponse {
    List<OrganizationProject> getData();

    static Builder builder();
}

Enums

MembershipRole

/**
 * Membership role levels
 */
public enum MembershipRole {
    OWNER,   // Full access, can manage billing
    ADMIN,   // Full access except billing
    MEMBER,  // Can create and view data
    VIEWER   // Read-only access
}

Complete Organization Management Example

import com.langfuse.client.LangfuseClient;
import com.langfuse.client.resources.projects.types.*;
import com.langfuse.client.resources.organizations.types.*;
import java.time.OffsetDateTime;
import java.time.format.DateTimeFormatter;

public class OrganizationManagementExample {
    public static void main(String[] args) {
        // Use organization-scoped API key
        LangfuseClient client = LangfuseClient.builder()
            .url("https://cloud.langfuse.com")
            .credentials("org-pk-...", "org-sk-...")
            .build();

        // 1. Create a new project - Note: Staged builder requires name() -> retention()
        CreateProjectRequest projectRequest = CreateProjectRequest.builder()
            .name("Customer Support Bot")  // Required first: project name
            .retention(0)  // Required second: retention days (0 = no retention limit)
            .build();

        Project project = client.projects().create(projectRequest);
        System.out.println("Created project: " + project.getName());

        // 2. Create API keys for the project
        CreateApiKeyRequest prodKeyRequest = CreateApiKeyRequest.builder()
            .note("Production Key")
            .build();

        ApiKeyResponse prodKey = client.projects()
            .createApiKey(project.getId(), prodKeyRequest);

        System.out.println("Production key created:");
        System.out.println("  Public key: " + prodKey.getPublicKey());
        System.out.println("  Secret key: " + prodKey.getSecretKey() + " (save this!)");

        CreateApiKeyRequest devKeyRequest = CreateApiKeyRequest.builder()
            .note("Development Key")
            .build();

        ApiKeyResponse devKey = client.projects()
            .createApiKey(project.getId(), devKeyRequest);

        // 3. Add team members to the organization
        MembershipRequest admin = MembershipRequest.builder()
            .email("admin@example.com")
            .role(MembershipRole.ADMIN)
            .build();

        client.organizations().updateOrganizationMembership(admin);

        MembershipRequest member = MembershipRequest.builder()
            .email("developer@example.com")
            .role(MembershipRole.MEMBER)
            .build();

        client.organizations().updateOrganizationMembership(member);

        // 4. Add specific users to the project
        MembershipRequest projectMember = MembershipRequest.builder()
            .email("developer@example.com")
            .role(MembershipRole.ADMIN)
            .build();

        client.organizations()
            .updateProjectMembership(project.getId(), projectMember);

        // 5. List all organization members
        MembershipsResponse orgMembers = client.organizations()
            .getOrganizationMemberships();

        System.out.println("\nOrganization members:");
        for (MembershipResponse memberResp : orgMembers.getData()) {
            System.out.println("  " + memberResp.getEmail() +
                             " (" + memberResp.getRole() + ")");
        }

        // 6. List project members
        MembershipsResponse projectMembers = client.organizations()
            .getProjectMemberships(project.getId());

        System.out.println("\nProject members:");
        for (MembershipResponse memberResp : projectMembers.getData()) {
            System.out.println("  " + memberResp.getEmail() +
                             " (" + memberResp.getRole() + ")");
        }

        // 7. List all API keys for the project
        ApiKeyList keys = client.projects().getApiKeys(project.getId());

        System.out.println("\nAPI keys:");
        for (ApiKeySummary key : keys.getData()) {
            key.getNote().ifPresent(note -> System.out.println("  " + note));
            System.out.println("    Created: " + key.getCreatedAt());
            System.out.println("    Last used: " +
                key.getLastUsedAt()
                    .map(dt -> dt.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
                    .orElse("never"));
        }

        // 8. List all projects in organization
        OrganizationProjectsResponse orgProjects = client.organizations()
            .getOrganizationProjects();

        System.out.println("\nOrganization projects:");
        for (OrganizationProject proj : orgProjects.getData()) {
            System.out.println("  " + proj.getName() +
                             " (your role: " + proj.getRole() + ")");
        }

        // 9. Clean up - delete old API key
        client.projects().deleteApiKey(project.getId(), devKey.getId());
        System.out.println("\nDeleted development key");
    }
}

Best Practices

  1. Organization Keys: Use organization-scoped keys for management operations
  2. Key Security: Save secret keys immediately - they're only shown once
  3. Key Rotation: Regularly rotate API keys for security
  4. Least Privilege: Assign minimum necessary role to each user
  5. Key Notes: Use descriptive notes for API keys to identify their purpose
  6. Audit Trail: Track key usage with lastUsedAt timestamps
  7. Project Isolation: Use separate projects for different environments
  8. Member Management: Regularly review organization and project memberships

API Key Types

Project-Scoped Keys

  • Created via createApiKey()
  • Access to single project only
  • Use for application integration
  • Format: pk-lf-... / sk-lf-...

Organization-Scoped Keys

  • Created in Langfuse UI
  • Access to organization management
  • Use for administration
  • Format: org-pk-... / org-sk-...

Related Documentation

  • Client Configuration - Using API keys
  • SCIM - Automated user provisioning

Install with Tessl CLI

npx tessl i tessl/maven-com-langfuse--langfuse-java

docs

client-configuration.md

comments-annotations.md

common-types.md

datasets.md

exceptions.md

health.md

index.md

ingestion.md

media.md

metrics.md

models.md

pagination.md

projects-organizations.md

prompts.md

scim.md

scores.md

sessions.md

traces-observations.md

tile.json