--- title: SCIM and Org API sidebarTitle: SCIM and Org API description: Langfuse is open and meant to be extended via custom workflows and integrations. You can use these endpoints to automate project and user management on your Langfuse organization. --- # SCIM & Organization-Key Scoped API Routes Via organization-scoped API keys, you can administer projects, users, and project/organization memberships (see [RBAC docs](/docs/administration/rbac)). Langfuse is open and meant to be extended via custom workflows and integrations. You can use these endpoints to automate project and user management on your Langfuse organization. This documentation covers organization management APIs, SCIM-compliant user provisioning endpoints, and includes a comprehensive guide for setting up Okta authentication and user provisioning with Langfuse. If you self-host Langfuse, you can use the [Instance Management API](/self-hosting/administration/instance-management-api) to administer organizations across an instance. ## Authentication Authenticate with the API using [Basic Auth](https://en.wikipedia.org/wiki/Basic_access_authentication). Organization scoped API keys can be created via the [Instance Management API](/self-hosting/administration/instance-management-api) or in the Organization Settings within the Langfuse UI. Example: ```bash curl -u public-key:secret-key https://cloud.langfuse.com/api/public/projects/{projectId}/apiKeys ``` ## Organization Management All applicable endpoints are marked with `(requires organization-scoped API key)`. Those include the following routes: - `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` See [API Reference](https://api.reference.langfuse.com) for more details. ## User Management via SCIM In addition, we implement the following [SCIM](https://datatracker.ietf.org/doc/html/rfc7642) compliant endpoints. Use `/api/public/scim` as the base URI for them. To create a new user within Langfuse, you can use the SCIM-style endpoints and `POST /Users`. This will create a new user if the email does not exist yet. Then it will add the user to the organization with role `NONE` (unless a `roles` attribute is provided, see [Okta guide below](#okta)). Afterward, the role can be updated using the membership endpoints either on an organization or a project level (see above). When SCIM deprovisions and re-provisions a user (e.g. during initial SCIM setup or IdP sync), the user's organization role may be overwritten with the role configured in the SCIM `roles` attribute (defaulting to `NONE`). To avoid accidental role downgrades, make sure the `roles` attribute in your IdP is set to the correct value - e.g. `OWNER` for organization owners - **before** enabling SCIM provisioning. To remove a user from an organization, call the `DELETE /Users/{id}` endpoint. This will not delete the user itself, only its membership with the organization. SCIM provisioning does not set a password. A `password` attribute in the request body is accepted for compatibility — Okta sends a placeholder value on every user create, even when password sync is disabled — but Langfuse ignores it, so provisioned users never receive a credential from SCIM. Provisioned users sign in via Single Sign-On (SSO), or set their own password through the "Forgot password" flow, which confirms that they control the email address. To authenticate provisioned users via SSO, you need to: - Langfuse Cloud: configure an Enterprise SSO provider ([docs](/security/auth)). - Self-hosted: configure `AUTH__ALLOW_ACCOUNT_LINKING` for your SSO provider to ensure that the user accounts are linked correctly [SSO Docs](/self-hosting/security/authentication-and-sso#additional-configuration). The following SCIM endpoints are available: - `GET /ServiceProviderConfig` - `GET /ResourceTypes` - `GET /Schemas` - `GET /Users` - `POST /Users` - `GET /Users/{id}` - `DELETE /Users/{id}` ### SCIM Vendor Guides [#scim-vendor-guides] #### Okta [#okta] This guide covers how to set up Okta user provisioning for Langfuse. **Okta requires two separate applications.** Okta does not support enabling [SCIM on a custom OIDC app](https://support.okta.com/help/s/article/configure-scim-for-a-custom-oidc-app?language=en_US). Configure: 1. An **OIDC application** for SSO — see [Authentication and SSO → Okta](/docs/administration/authentication-and-sso#okta) 2. A separate **SAML application** for SCIM provisioning — steps below The SSO settings on the SCIM/SAML application do not need to work; Langfuse uses the OIDC app for authentication. Langfuse supports the SCIM 2.0 protocol for user provisioning. After your OIDC SSO app is in place, create a second Okta application for SCIM: 1. **Create a SAML application for SCIM** (separate from your OIDC SSO app): - Log in to your Okta admin console. - Navigate to **Applications** > **Create App Integration**. - Choose **SAML 2.0** as the sign-in method and click **Next**. - Fill in the application settings. Use your self-hosted domain or one of the Langfuse Cloud domains. - **App name**: `Langfuse SCIM` - **Single sign-on URL**: `https://your-langfuse-domain.com` (placeholder only — Langfuse authenticates via the OIDC app, not this SAML SSO URL) - **Audience URI**: `langfuse` - Click **Next** and then **Finish**. 2. **Configure SCIM Settings**: - In the **General** tab, set `Provisioning` to SCIM. - In the **Provisioning** tab, edit your **SCIM Connection**. - Enter your credentials: - **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**: Use a public key from your Organization settings. - **Basic Auth - Password**: Use a private key from your Organization settings. - Test the API credentials and press **Save**. 3. **Configure Provisioning**: - In the **Provisioning** tab, enable the following options: - **Create Users** - **Update User Attributes** - **Deactivate Users** - Click **Save**. 4. **Add Default User Permissions** (Optional): - In the **Provisioning** tab, go to the Profile Editor and add a new `roles` attribute: - **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` - In the **Provisioning** tab, modify the `roles` attribute to set default permissions for new users. - You can set it for all users of the application to provide a default. Set it to "NONE", "VIEWER", "MEMBER", "ADMIN", or "OWNER". 5. **Assign Users**: - Navigate to the **Assignments** tab. - Click **Assign** > **Assign to People**. - Select the users you want to assign to the Langfuse SCIM application. You can overwrite the role here. - Click **Done** and then **Save**. - Users should appear as Member within your Langfuse Organization. ##### Troubleshooting - **Users are provisioned with NONE/VIEWER permissions instead of their intended `role`**: This usually happens if the `roles` attribute has an attribute type `Group` instead of `Personal`. - **User lost their role after enabling SCIM**: During initial SCIM setup, if a user is deprovisioned and re-provisioned, their organization role is overwritten with the value from the SCIM `roles` attribute. If no role is configured in the IdP, the default is `NONE`. To fix this, ensure the correct role (including `OWNER` for organization owners) is set in the IdP profile before provisioning. --- ## Agent Instructions This page is part of the [Langfuse](https://langfuse.com) documentation, published as plain Markdown for AI agents. Every page is available as Markdown by appending `.md` to its URL, or by sending an `Accept: text/markdown` header. This page: `https://langfuse.com/docs/administration/scim-and-org-api.md`. ### Querying these docs If the answer is not on this page, query the documentation instead of guessing: - **Semantic search** across all Langfuse docs, returning an answer with the relevant pages and excerpts. Ask a specific, self-contained question: ```bash curl -sG "https://langfuse.com/api/search-docs" --data-urlencode "query=How do I trace a LangGraph agent?" ``` - **Index of every page**: , with per-section indexes [llms-docs.txt](https://langfuse.com/llms-docs.txt), [llms-integrations.txt](https://langfuse.com/llms-integrations.txt), and [llms-self-hosting.txt](https://langfuse.com/llms-self-hosting.txt). ### Before writing Langfuse code - **Install the [Langfuse Agent Skill](https://langfuse.com/docs/api-and-data-platform/features/agent-skill).** It encodes Langfuse's own best practices for instrumentation, prompt management, and evaluation, and materially improves results. - **Read [What does a good trace look like?](https://langfuse.com/docs/observability/best-practices.md)** before instrumenting an application. - **Verify endpoints, parameters, and response fields** against the [API reference](https://api.reference.langfuse.com) instead of inferring them from code examples. - **Use the [Langfuse CLI](https://langfuse.com/docs/api-and-data-platform/features/cli)** (`npx langfuse-cli api `) to read or write traces, prompts, datasets, and scores from the terminal. Found an error in these docs? Please open an issue at .