0
# Projects and Organizations
1

2
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.
3

4
## Capabilities
5

6
### ProjectsClient
7

8
Client for managing projects and API keys.
9

10
```java { .api }
11
/**
12
 * Get projects associated with the API key
13
 *
14
 * @param requestOptions Optional request configuration
15
 */
16
Projects get();
17
Projects get(RequestOptions requestOptions);
18

19
/**
20
 * Create a new project
21
 * Requires organization-scoped API key
22
 *
23
 * @param request Project definition
24
 * @param requestOptions Optional request configuration
25
 */
26
Project create(CreateProjectRequest request);
27
Project create(CreateProjectRequest request, RequestOptions requestOptions);
28

29
/**
30
 * Update a project by ID
31
 * Requires organization-scoped API key
32
 *
33
 * @param projectId Project ID
34
 * @param request Update data
35
 * @param requestOptions Optional request configuration
36
 */
37
Project update(String projectId, UpdateProjectRequest request);
38
Project update(String projectId, UpdateProjectRequest request, RequestOptions requestOptions);
39

40
/**
41
 * Delete a project by ID (asynchronous operation)
42
 * Requires organization-scoped API key
43
 *
44
 * @param projectId Project ID
45
 * @param requestOptions Optional request configuration
46
 */
47
ProjectDeletionResponse delete(String projectId);
48
ProjectDeletionResponse delete(String projectId, RequestOptions requestOptions);
49

50
/**
51
 * Get all API keys for a project
52
 * Requires organization-scoped API key
53
 *
54
 * @param projectId Project ID
55
 * @param requestOptions Optional request configuration
56
 */
57
ApiKeyList getApiKeys(String projectId);
58
ApiKeyList getApiKeys(String projectId, RequestOptions requestOptions);
59

60
/**
61
 * Create a new API key for a project
62
 * Requires organization-scoped API key
63
 *
64
 * @param projectId Project ID
65
 * @param request API key configuration
66
 * @param requestOptions Optional request configuration
67
 */
68
ApiKeyResponse createApiKey(String projectId);
69
ApiKeyResponse createApiKey(String projectId, CreateApiKeyRequest request);
70
ApiKeyResponse createApiKey(String projectId, CreateApiKeyRequest request, RequestOptions requestOptions);
71

72
/**
73
 * Delete an API key for a project
74
 * Requires organization-scoped API key
75
 *
76
 * @param projectId Project ID
77
 * @param apiKeyId API key ID
78
 * @param requestOptions Optional request configuration
79
 */
80
ApiKeyDeletionResponse deleteApiKey(String projectId, String apiKeyId);
81
ApiKeyDeletionResponse deleteApiKey(String projectId, String apiKeyId, RequestOptions requestOptions);
82
```
83

84
**Usage Examples:**
85

86
```java
87
import com.langfuse.client.LangfuseClient;
88
import com.langfuse.client.resources.projects.types.*;
89
import com.langfuse.client.resources.projects.requests.CreateProjectRequest;
90
import java.time.OffsetDateTime;
91

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

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

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

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

112
// Update a project
113
UpdateProjectRequest updateRequest = UpdateProjectRequest.builder()
114
    .name("Updated Project Name")
115
    .build();
116

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

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

126
// Create an API key
127
CreateApiKeyRequest keyRequest = CreateApiKeyRequest.builder()
128
    .note("Production Key")
129
    .build();
130

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

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

139
// Delete a project
140
ProjectDeletionResponse projectDelete = client.projects()
141
    .delete(newProject.getId());
142
```
143

144
### OrganizationsClient
145

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

148
```java { .api }
149
/**
150
 * Get all memberships for the organization
151
 * Requires organization-scoped API key
152
 *
153
 * @param requestOptions Optional request configuration
154
 */
155
MembershipsResponse getOrganizationMemberships();
156
MembershipsResponse getOrganizationMemberships(RequestOptions requestOptions);
157

158
/**
159
 * Create or update an organization membership
160
 * Requires organization-scoped API key
161
 *
162
 * @param request Membership definition
163
 * @param requestOptions Optional request configuration
164
 */
165
MembershipResponse updateOrganizationMembership(MembershipRequest request);
166
MembershipResponse updateOrganizationMembership(MembershipRequest request, RequestOptions requestOptions);
167

168
/**
169
 * Get all memberships for a specific project
170
 * Requires organization-scoped API key
171
 *
172
 * @param projectId Project ID
173
 * @param requestOptions Optional request configuration
174
 */
175
MembershipsResponse getProjectMemberships(String projectId);
176
MembershipsResponse getProjectMemberships(String projectId, RequestOptions requestOptions);
177

178
/**
179
 * Create or update a project membership
180
 * Requires organization-scoped API key
181
 *
182
 * @param projectId Project ID
183
 * @param request Membership definition
184
 * @param requestOptions Optional request configuration
185
 */
186
MembershipResponse updateProjectMembership(String projectId, MembershipRequest request);
187
MembershipResponse updateProjectMembership(String projectId, MembershipRequest request, RequestOptions requestOptions);
188

189
/**
190
 * Get all projects for the organization
191
 * Requires organization-scoped API key
192
 *
193
 * @param requestOptions Optional request configuration
194
 */
195
OrganizationProjectsResponse getOrganizationProjects();
196
OrganizationProjectsResponse getOrganizationProjects(RequestOptions requestOptions);
197
```
198

199
**Usage Examples:**
200

201
```java
202
import com.langfuse.client.resources.organizations.types.*;
203

204
// Get organization memberships
205
MembershipsResponse orgMembers = client.organizations()
206
    .getOrganizationMemberships();
207

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

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

218
MembershipResponse newMember = client.organizations()
219
    .updateOrganizationMembership(memberRequest);
220

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

225
// Add a user to a project
226
MembershipRequest projectMemberRequest = MembershipRequest.builder()
227
    .email("user@example.com")
228
    .role(MembershipRole.ADMIN)
229
    .build();
230

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

234
// Get all organization projects
235
OrganizationProjectsResponse orgProjects = client.organizations()
236
    .getOrganizationProjects();
237

238
for (OrganizationProject project : orgProjects.getData()) {
239
    System.out.println(project.getName() + " - Role: " + project.getRole());
240
}
241
```
242

243
## Request Types
244

245
### CreateProjectRequest
246

247
```java { .api }
248
/**
249
 * Request for creating a project
250
 *
251
 * Staged Builder Pattern (required order):
252
 * 1. name(String) - Project name (required first)
253
 * 2. retention(int) - Data retention days (required second)
254
 *    Must be 0 or at least 3 days
255
 * 3. metadata(Map<String, Object>) - Optional metadata
256
 * 4. build() - Build the request
257
 */
258
public final class CreateProjectRequest {
259
    String getName();  // Project name
260
    Optional<Map<String, Object>> getMetadata();  // Optional metadata
261
    int getRetention();  // Data retention days (required)
262

263
    static NameStage builder();  // Returns staged builder starting with name()
264
}
265
```
266

267
### UpdateProjectRequest
268

269
```java { .api }
270
/**
271
 * Request for updating a project
272
 */
273
public final class UpdateProjectRequest {
274
    String getName();  // New project name
275

276
    static Builder builder();
277
}
278
```
279

280
### CreateApiKeyRequest
281

282
```java { .api }
283
/**
284
 * Request for creating an API key
285
 */
286
public final class CreateApiKeyRequest {
287
    Optional<String> getNote();  // Optional note for the API key
288

289
    static Builder builder();
290
}
291
```
292

293
### MembershipRequest
294

295
```java { .api }
296
/**
297
 * Request for creating or updating a membership
298
 */
299
public final class MembershipRequest {
300
    String getEmail();         // User email
301
    MembershipRole getRole();  // OWNER, ADMIN, MEMBER, VIEWER
302

303
    static Builder builder();
304
}
305
```
306

307
## Response Types
308

309
### Project
310

311
```java { .api }
312
/**
313
 * Project definition
314
 */
315
public final class Project {
316
    String getId();
317
    String getName();
318
    Map<String, Object> getMetadata();       // Metadata for the project
319
    Optional<Integer> getRetentionDays();    // Number of days to retain data
320

321
    static Builder builder();
322
}
323
```
324

325
### Projects
326

327
```java { .api }
328
/**
329
 * List of projects
330
 */
331
public final class Projects {
332
    List<Project> getData();
333

334
    static Builder builder();
335
}
336
```
337

338
### ProjectDeletionResponse
339

340
```java { .api }
341
/**
342
 * Response after deleting a project
343
 */
344
public final class ProjectDeletionResponse {
345
    boolean getSuccess();
346

347
    static Builder builder();
348
}
349
```
350

351
### ApiKeySummary
352

353
```java { .api }
354
/**
355
 * Summary information about an API key
356
 * Note: Secret key is never returned in summaries
357
 */
358
public final class ApiKeySummary {
359
    String getId();
360
    OffsetDateTime getCreatedAt();
361
    Optional<OffsetDateTime> getExpiresAt();
362
    Optional<OffsetDateTime> getLastUsedAt();
363
    Optional<String> getNote();          // Optional note for the key
364
    String getPublicKey();
365
    String getDisplaySecretKey();        // Partially masked secret key
366

367
    static Builder builder();
368
}
369
```
370

371
### ApiKeyList
372

373
```java { .api }
374
/**
375
 * List of API keys
376
 */
377
public final class ApiKeyList {
378
    List<ApiKeySummary> getData();
379

380
    static Builder builder();
381
}
382
```
383

384
### ApiKeyResponse
385

386
```java { .api }
387
/**
388
 * Response after creating an API key
389
 * Contains both public and secret keys
390
 * WARNING: Secret key is only shown once - save it immediately!
391
 */
392
public final class ApiKeyResponse {
393
    String getId();
394
    OffsetDateTime getCreatedAt();
395
    String getPublicKey();           // Public key
396
    String getSecretKey();           // Secret key (only shown once!)
397
    String getDisplaySecretKey();    // Partially masked secret key
398
    Optional<String> getNote();      // Optional note for the key
399

400
    static Builder builder();
401
}
402
```
403

404
### ApiKeyDeletionResponse
405

406
```java { .api }
407
/**
408
 * Response after deleting an API key
409
 */
410
public final class ApiKeyDeletionResponse {
411
    boolean getSuccess();
412

413
    static Builder builder();
414
}
415
```
416

417
### MembershipResponse
418

419
```java { .api }
420
/**
421
 * Membership information
422
 */
423
public final class MembershipResponse {
424
    String getId();
425
    String getEmail();
426
    MembershipRole getRole();
427
    Optional<String> getName();  // User display name
428

429
    static Builder builder();
430
}
431
```
432

433
### MembershipsResponse
434

435
```java { .api }
436
/**
437
 * List of memberships
438
 */
439
public final class MembershipsResponse {
440
    List<MembershipResponse> getData();
441

442
    static Builder builder();
443
}
444
```
445

446
### OrganizationProject
447

448
```java { .api }
449
/**
450
 * Project with user's role
451
 */
452
public final class OrganizationProject {
453
    String getId();
454
    String getName();
455
    MembershipRole getRole();  // User's role in the project
456

457
    static Builder builder();
458
}
459
```
460

461
### OrganizationProjectsResponse
462

463
```java { .api }
464
/**
465
 * List of organization projects
466
 */
467
public final class OrganizationProjectsResponse {
468
    List<OrganizationProject> getData();
469

470
    static Builder builder();
471
}
472
```
473

474
## Enums
475

476
### MembershipRole
477

478
```java { .api }
479
/**
480
 * Membership role levels
481
 */
482
public enum MembershipRole {
483
    OWNER,   // Full access, can manage billing
484
    ADMIN,   // Full access except billing
485
    MEMBER,  // Can create and view data
486
    VIEWER   // Read-only access
487
}
488
```
489

490
## Complete Organization Management Example
491

492
```java
493
import com.langfuse.client.LangfuseClient;
494
import com.langfuse.client.resources.projects.types.*;
495
import com.langfuse.client.resources.organizations.types.*;
496
import java.time.OffsetDateTime;
497
import java.time.format.DateTimeFormatter;
498

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

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

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

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

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

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

528
        CreateApiKeyRequest devKeyRequest = CreateApiKeyRequest.builder()
529
            .note("Development Key")
530
            .build();
531

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

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

541
        client.organizations().updateOrganizationMembership(admin);
542

543
        MembershipRequest member = MembershipRequest.builder()
544
            .email("developer@example.com")
545
            .role(MembershipRole.MEMBER)
546
            .build();
547

548
        client.organizations().updateOrganizationMembership(member);
549

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

556
        client.organizations()
557
            .updateProjectMembership(project.getId(), projectMember);
558

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

563
        System.out.println("\nOrganization members:");
564
        for (MembershipResponse memberResp : orgMembers.getData()) {
565
            System.out.println("  " + memberResp.getEmail() +
566
                             " (" + memberResp.getRole() + ")");
567
        }
568

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

573
        System.out.println("\nProject members:");
574
        for (MembershipResponse memberResp : projectMembers.getData()) {
575
            System.out.println("  " + memberResp.getEmail() +
576
                             " (" + memberResp.getRole() + ")");
577
        }
578

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

582
        System.out.println("\nAPI keys:");
583
        for (ApiKeySummary key : keys.getData()) {
584
            key.getNote().ifPresent(note -> System.out.println("  " + note));
585
            System.out.println("    Created: " + key.getCreatedAt());
586
            System.out.println("    Last used: " +
587
                key.getLastUsedAt()
588
                    .map(dt -> dt.format(DateTimeFormatter.ISO_OFFSET_DATE_TIME))
589
                    .orElse("never"));
590
        }
591

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

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

602
        // 9. Clean up - delete old API key
603
        client.projects().deleteApiKey(project.getId(), devKey.getId());
604
        System.out.println("\nDeleted development key");
605
    }
606
}
607
```
608

609
## Best Practices
610

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

620
## API Key Types
621

622
### Project-Scoped Keys
623
- Created via `createApiKey()`
624
- Access to single project only
625
- Use for application integration
626
- Format: `pk-lf-...` / `sk-lf-...`
627

628
### Organization-Scoped Keys
629
- Created in Langfuse UI
630
- Access to organization management
631
- Use for administration
632
- Format: `org-pk-...` / `org-sk-...`
633

634
## Related Documentation
635

636
- [Client Configuration](./client-configuration.md) - Using API keys
637
- [SCIM](./scim.md) - Automated user provisioning
638