SCIM & 조직키 범위 API 라우트(Organization-Key Scoped API Routes)

조직 범위의 API 키를 사용하면 프로젝트, 사용자, 프로젝트/조직 멤버십을 관리할 수 있습니다. 이 문서는 조직 관리 API, SCIM 호환 사용자 프로비저닝 엔드포인트, 그리고 Okta 인증 및 사용자 프로비저닝을 Langfuse와 함께 설정하는 가이드를 다룹니다.

출처: 문서

본문

이 기능은 어디에서 쓸 수 있나요?

플랜	사용 가능 여부
Hobby	사용 불가
Core	사용 불가
Pro	사용 불가
Enterprise	사용 가능
Self Hosted	Enterprise Edition

조직 범위의 API 키를 통해 프로젝트, 사용자, 프로젝트/조직 멤버십을 관리할 수 있습니다(RBAC 문서 참고).

Langfuse는 개방적이며 커스텀 워크플로우와 통합으로 확장되도록 설계되었습니다. 이 엔드포인트를 사용해 Langfuse 조직의 프로젝트 및 사용자 관리를 자동화할 수 있습니다.

이 문서는 조직 관리 API, SCIM 호환 사용자 프로비저닝 엔드포인트를 다루며, Langfuse와 함께 Okta 인증 및 사용자 프로비저닝을 설정하는 종합 가이드를 포함합니다.

셀프 호스팅한다면 Instance Management API 로 인스턴스 전체에서 조직을 관리할 수 있습니다.

인증

API 인증은 Basic Auth 를 사용합니다. 조직 범위 API 키는 Instance Management API 나 Langfuse UI의 Organization Settings에서 만들 수 있습니다.

예시:

curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects/{projectId}/apiKeys

조직 관리(Organization Management)

해당되는 모든 엔드포인트는 (requires organization-scoped API key)로 표시됩니다. 여기에는 다음 라우트가 포함됩니다:

POST /api/public/projects
PUT /api/public/projects/{projectId}
DELETE /api/public/projects/{projectId}
GET /api/public/projects/{projectId}/apiKeys
POST /api/public/projects/{projectId}/apiKeys
DELETE /api/public/projects/{projectId}/apiKeys/{apiKeyId}
PUT /api/public/organizations/memberships
GET /api/public/organizations/memberships
PUT /api/public/projects/{projectId}/memberships
DELETE /api/public/projects/{projectId}/memberships

자세한 내용은 API Reference 를 참고하세요.

SCIM을 통한 사용자 관리

또한 다음 SCIM 호환 엔드포인트를 구현합니다. 기본 URI로 /api/public/scim을 사용하세요.

Langfuse에서 새 사용자를 만들려면 SCIM 스타일 엔드포인트와 POST /Users를 사용할 수 있습니다. 이메일이 아직 없으면 새 사용자가 생성됩니다. 그런 다음 roles 속성이 제공되지 않는 한(아래 Okta 가이드 참고) 역할 NONE으로 사용자가 조직에 추가됩니다.

이후 역할은 조직 또는 프로젝트 수준의 멤버십 엔드포인트로 업데이트할 수 있습니다 (위 참고).

SCIM이 사용자를 deprovision/재provision할 때(예: 초기 SCIM 설정이나 IdP 동기화 중), 사용자의 조직 역할이 SCIM roles 속성에 구성된 역할(기본값 NONE)로 덮어써질 수 있습니다. 의도치 않은 역할 하향을 피하려면 SCIM 프로비저닝을 활성화하기 전에 IdP의 roles 속성이 올바른 값(예: 조직 소유자는 OWNER)으로 설정되어 있는지 확인하세요.

조직에서 사용자를 제거하려면 DELETE /Users/{id} 엔드포인트를 호출하세요. 이는 사용자 자체를 삭제하지 않고 조직과의 멤버십만 삭제합니다.

SCIM 프로비저닝은 비밀번호를 설정하지 않습니다. 요청 본문의 password 속성은 호환성을 위해 허용되지만(Okta는 비밀번호 동기화가 비활성화된 경우에도 사용자 생성마다 placeholder 값을 보냄), Langfuse는 이를 무시하므로 프로비저닝된 사용자는 SCIM에서 자격 증명을 받지 못합니다. 프로비저닝된 사용자는 Single Sign-On(SSO)으로 로그인하거나, "Forgot password" 흐름으로 자신의 비밀번호를 설정합니다(이메일 주소를 제어함을 확인).

프로비저닝된 사용자를 SSO로 인증하려면:

Langfuse Cloud: Enterprise SSO 제공자 구성 (docs)
셀프 호스팅: SSO 제공자에 대해 AUTH_<PROVIDER>_ALLOW_ACCOUNT_LINKING을 구성해 사용자 계정이 올바르게 연결되도록 하세요 (SSO Docs)

다음 SCIM 엔드포인트를 사용할 수 있습니다:

GET /ServiceProviderConfig
GET /ResourceTypes
GET /Schemas
GET /Users
POST /Users
GET /Users/{id}
DELETE /Users/{id}

SCIM 벤더 가이드

Okta

이 가이드는 Langfuse용 Okta 사용자 프로비저닝을 설정하는 방법을 다룹니다.

Okta에는 두 개의 별도 애플리케이션이 필요합니다. Okta는 커스텀 OIDC 앱에서 SCIM 활성화 를 지원하지 않습니다. 다음과 같이 구성하세요:

SSO용 OIDC 애플리케이션 — Authentication and SSO → Okta 참고
SCIM 프로비저닝용 별도 SAML 애플리케이션 — 아래 단계

SCIM/SAML 애플리케이션의 SSO 설정은 동작할 필요가 없습니다. Langfuse는 인증에 OIDC 앱을 사용합니다.

Langfuse는 사용자 프로비저닝에 SCIM 2.0 프로토콜을 지원합니다. OIDC SSO 앱을 마련한 후 SCIM용 두 번째 Okta 애플리케이션을 만드세요:

SCIM용 SAML 애플리케이션 생성(OIDC SSO 앱과 별도):

Okta admin console에 로그인
Applications > Create App Integration으로 이동
sign-in method로 SAML 2.0 선택 후 Next 클릭

애플리케이션 설정을 채우세요. 내 셀프 호스팅 도메인이나 Langfuse Cloud 도메인 중 하나를 사용하세요.

App name: Langfuse SCIM
Single sign-on URL: https://your-langfuse-domain.com (placeholder일 뿐 — Langfuse는 이 SAML SSO URL이 아닌 OIDC 앱으로 인증)
Audience URI: langfuse
Next 클릭 후 Finish 클릭

SCIM 설정 구성:

General 탭에서 Provisioning을 SCIM으로 설정
Provisioning 탭에서 SCIM Connection 편집

자격 증명 입력:

SCIM connector base URL: https://your-langfuse-domain.com/api/public/scim
Unique identifier field for users: userName
Supported provisioning actions: Import new Users and Profile Updates, Push New Users, Push Profile Updates
Basic Auth - Username: Organization 설정의 공개 키 사용
Basic Auth - Password: Organization 설정의 비공개 키 사용
API 자격 증명을 테스트하고 Save 누르기

프로비저닝 구성:

Provisioning 탭에서 다음 옵션을 활성화:

Create Users
Update User Attributes
Deactivate Users

Save 클릭.

기본 사용자 권한 추가(선택):

Provisioning 탭의 Profile Editor에서 새 roles 속성을 추가:

Data type: string array
Display Name: Langfuse Roles
Variable Name: roles
External Name: roles
External Namespace: urn:ietf:params:scim:schemas:core:2.0:User
Attribute members: NONE, VIEWER, MEMBER, ADMIN, OWNER
Attribute type: Personal
Provisioning 탭에서 roles 속성을 수정해 새 사용자의 기본 권한을 설정
애플리케이션의 모든 사용자에 대해 기본값으로 설정할 수 있습니다. "NONE", "VIEWER", "MEMBER", "ADMIN", 또는 "OWNER"로 설정하세요.

사용자 할당:

Assignments 탭으로 이동
Assign > Assign to People 클릭
Langfuse SCIM 애플리케이션에 할당할 사용자를 선택. 여기서 역할을 덮어쓸 수 있습니다.
Done 클릭 후 Save 클릭
사용자는 내 Langfuse 조직에서 Member로 표시됩니다.

트러블슈팅

사용자가 의도한 role 대신 NONE/VIEWER 권한으로 프로비저닝됩니다: 보통 roles 속성의 attribute type이 Personal이 아니라 Group일 때 발생합니다.
SCIM 활성화 후 사용자가 역할을 잃었습니다: 초기 SCIM 설정 중 사용자가 deprovision된 뒤 재provision되면 조직 역할이 SCIM roles 속성의 값으로 덮어써집니다. IdP에 역할이 구성돼 있지 않으면 기본값은 NONE입니다. 이를 고치려면 프로비저닝 전에 IdP 프로필에 올바른 역할(조직 소유자의 OWNER 포함)이 설정돼 있는지 확인하세요.

더 알아보기 (Learn more)

출처 문서: SCIM & 조직키 범위 API 라우트(Organization-Key Scoped API Routes)