Manage users, groups, and roles with SCIM ↗

wandb guide intermediate deployment
no

Original Documentation

Documentation Index#

Fetch the complete documentation index at: https://docs.wandb.ai/llms.txt Use this file to discover all available pages before exploring further.

Watch a video demonstrating SCIM in action (12 min)

Overview#

The System for Cross-domain Identity Management (SCIM) API allows instance or organization admins to manage users, groups, and custom roles in their W&B organization. SCIM groups map to W&B Teams.

W&B’s SCIM API is compatible with major identity providers including Okta, enabling automated user provisioning and deprovisioning. For SSO configuration with Okta and other identity providers, see the SSO documentation.

For practical Python examples demonstrating how to interact with the SCIM API, visit our wandb-scim repository.

Supported Features#

  • Filtering: The API supports filtering for /Users and /Groups endpoints
  • PATCH Operations: Supports PATCH for partial resource updates
  • ETag Support: Conditional updates using ETags for conflict detection
  • Service Account Authentication: Organization service accounts can access the API

If you are an admin of multiple Enterprise Multi-tenant SaaS organizations, you must configure the organization where SCIM API requests are sent to ensure SCIM API requests sent using your API Key affect the correct organization. Click your profile image, then click User Settings, then check the setting Default API organization.

The chosen hosting option determines the value for the <host-url> placeholder used in the examples in this page.

In addition, examples use user IDs such as abc and def. Real requests and responses have hashed values for user IDs.

Authentication#

Choose to authenticate using a user identity or a service account, after reviewing the key differences.

Key differences#

  • Who should use it: Users are best for interactive, one-off admin actions; service accounts are best for automation and integrations (CI/CD, provisioning tools).
  • Credentials: Users send username and API key; service accounts send only an API key (no username).
  • Authorization header payload: Users encode username:API-KEY; service accounts encode :API-KEY (leading colon).
  • Scope and permissions: Both require admin privileges; service accounts are organization-scoped and headless, providing clearer audit trails for automation.
  • Where to get credentials: Users copy their API key from User Settings; service account keys are in the organization’s Service account tab.
  • Multi-tenant Cloud: If you have access to more than one Multi-tenant Cloud organizations, you must set the Default API organization to ensure that SCIM API calls are routed to the intended organization.

Users#

Use your personal admin credentials when performing interactive admin tasks. Construct the HTTP Authorization header as Basic <base64(username:API-KEY)>.

For example, authorize as demo:p@55w0rd:

Authorization: Basic ZGVtbzpwQDU1dzByZA==

Service accounts#

Use an organization-scoped service account for automation or integrations. Construct the HTTP Authorization header as Basic <base64(:API-KEY)> (note the leading colon and empty username). Find service account API keys in the organization dashboard under the Service account tab. Refer to Organization-scoped service accounts.

For example, authorize with API key sa-p@55w0rd:

Authorization: Basic OnNhLXBANTV3MHJk

User management#

The SCIM user resource maps to W&B users. Use these endpoints to manage users in your organization.

Get user#

Retrieves information for a specific user in your organization.

This operation does not retrieve service accounts.

Endpoint#

  • URL: <host-url>/scim/Users/{id}
  • Method: GET

Parameters#

ParameterTypeRequiredDescription
idstringYesThe unique ID of the user

Example#

    GET /scim/Users/abc
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Get User Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "daysActive": 42,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "lastActiveAt": "2023-10-15T14:32:10Z",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1"
    }
    ```

The response includes details about the user's activity in the organization:

* **`daysActive`**: Total number of days the user has been active in the organization.
* **`lastActiveAt`**: ISO 8601 timestamp of the user's most recent activity. Returns `null` if the user has never been active.

The definition of "active" differs by deployment type:

* **Dedicated Cloud / Self-Managed**: A user is active if they sign in, open any page in the W\&B App, log runs, use the SDK, or interact with the W\&B server in any way.
* **Multi-tenant Cloud**: A user is active if they perform any auditable action scoped to the organization after May 8, 2025. See [Audit logging actions](/platform/hosting/monitoring-usage/audit-logging#actions) for the full list.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### List users

Retrieves a list of all users in your organization.

<span class="callout-start" data-callout-type="note"></span>This operation does not retrieve service accounts.<span class="callout-end"></span>

#### Filter users

The `/Users` endpoint supports filtering users by username or email:

* `userName eq "value"` - Filter by username
* `emails.value eq "value"` - Filter by email address

##### Example

```bash
GET /scim/Users?filter=userName eq "john.doe"
GET /scim/Users?filter=emails.value eq "john@example.com"

Endpoint#

  • URL: <host-url>/scim/Users
  • Method: GET

Example#

    GET /scim/Users
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="List Users Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "Resources": [
            {
                "active": true,
                "daysActive": 42,
                "displayName": "Dev User 1",
                "emails": {
                    "Value": "dev-user1@example.com",
                    "Display": "",
                    "Type": "",
                    "Primary": true
                },
                "id": "abc",
                "lastActiveAt": "2023-10-15T14:32:10Z",
                "meta": {
                    "resourceType": "User",
                    "created": "2023-10-01T00:00:00Z",
                    "lastModified": "2023-10-01T00:00:00Z",
                    "location": "Users/abc"
                },
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:User"
                ],
                "userName": "dev-user1"
            }
        ],
        "itemsPerPage": 9999,
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "startIndex": 1,
        "totalResults": 1
    }
    ```

The response includes details about each user's activity in the organization:

* **`daysActive`**: Total number of days the user has been active in the organization.
* **`lastActiveAt`**: ISO 8601 timestamp of the user's most recent activity. Returns `null` if the user has never been active.

The definition of "active" differs by deployment type:

* **Dedicated Cloud / Self-Managed**: A user is active if they sign in, open any page in the W\&B App, log runs, use the SDK, or interact with the W\&B server in any way.
* **Multi-tenant Cloud**: A user is active if they perform any auditable action scoped to the organization after May 8, 2025. See [Audit logging actions](/platform/hosting/monitoring-usage/audit-logging#actions) for the full list.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Create User

Creates a new user in your organization.

#### Endpoint

* **URL**: `<host-url>/scim/Users`
* **Method**: POST

#### Parameters

| Parameter  | Type   | Required | Description                                          |
| ---------- | ------ | -------- | ---------------------------------------------------- |
| `emails`   | array  | Yes      | Array of email objects. Must include a primary email |
| `userName` | string | Yes      | The username for the new user                        |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Create User Request (Dedicated/Self-Managed)"></span>
```bash
    POST /scim/Users
    ```

```json
    {
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "emails": [
            {
                "primary": true,
                "value": "dev-user2@example.com"
            }
        ],
        "userName": "dev-user2"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Create User Request (Multi-tenant)"></span>
```bash
    POST /scim/Users
    ```

```json
    {
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:teams:2.0:User"
        ],
        "emails": [
            {
                "primary": true,
                "value": "dev-user2@example.com"
            }
        ],
        "userName": "dev-user2",
        "urn:ietf:params:scim:schemas:extension:teams:2.0:User": {
            "teams": ["my-team"]
        }
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

#### Response

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Create User Response (Dedicated/Self-Managed)"></span>
```bash
    (Status 201)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 2",
        "emails": {
            "Value": "dev-user2@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "def",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "location": "Users/def"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user2"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Create User Response (Multi-tenant)"></span>
```bash
    (Status 201)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 2",
        "emails": {
            "Value": "dev-user2@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "def",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "location": "Users/def"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User",
            "urn:ietf:params:scim:schemas:extension:teams:2.0:User"
        ],
        "userName": "dev-user2",
        "organizationRole": "member",
        "teamRoles": [
            {
                "teamName": "my-team",
                "roleName": "member"
            }
        ],
        "groups": [
            {
                "value": "my-team-id"
            }
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Delete User

<span class="callout-start" data-callout-type="warning"></span>
  **Maintain admin access**

  You must ensure that at least one admin user exists in your instance or organization at all times. Otherwise, no user will be able to configure or maintain your organization's W\&B account. If an organization uses SCIM or another automated process to deprovision users from W\&B, a deprovisioning operation could inadvertently remove the last remaining admin from the instance or organization.

  For assistance with developing operational procedures, or to restore admin access, contact [support](mailto:support@wandb.com).
<span class="callout-end"></span>

Fully deletes a user from your organization.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Delete a service account in the settings for the W\&B Team.<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: DELETE

#### Parameters

| Parameter | Type   | Required | Description                         |
| --------- | ------ | -------- | ----------------------------------- |
| `id`      | string | Yes      | The unique ID of the user to delete |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Delete User Request"></span>
```bash
    DELETE /scim/Users/abc
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Delete User Response"></span>
```bash
    (Status 204)
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

<span class="callout-start" data-callout-type="note"></span>
  To temporarily deactivate the user, refer to [Deactivate user](#deactivate-user) API which uses the `PATCH` endpoint.
<span class="callout-end"></span>

### Update user email

Updates a user's primary email address.
**Not supported for Multi-tenant Cloud**, where a user's account is not managed by the organization.

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                 |
| --------- | ------ | -------- | --------------------------- |
| `id`      | string | Yes      | The unique ID of the user   |
| `op`      | string | Yes      | `replace`                   |
| `path`    | string | Yes      | `emails`                    |
| `value`   | array  | Yes      | Array with new email object |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Update Email Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "emails",
                "value": [
                    {
                        "value": "newemail@example.com",
                        "primary": true
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Update Email Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "newemail@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Update user display name

Updates a user's display name.
**Not supported for Multi-tenant Cloud**, where a user's account is not managed by the organization.

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description               |
| --------- | ------ | -------- | ------------------------- |
| `id`      | string | Yes      | The unique ID of the user |
| `op`      | string | Yes      | `replace`                 |
| `path`    | string | Yes      | `displayName`             |
| `value`   | string | Yes      | New display name          |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Update Display Name Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "displayName",
                "value": "John Doe"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Update Display Name Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "John Doe",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2025-7-01T00:00:00Z",
            "lastModified": "2025-7-01T00:00:00Z",
            "location": "users/dev-user1"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Deactivate user

Deactivates a user in your organization. The actual result differs by deployment type:

* **Dedicated Cloud** / **Self-Managed**: Sets the user's `active` field to `false`. To restore a deactivated user's access your organization, see [Reactivate user](#reactivate-user).
* **Multi-tenant Cloud**: Removes the user from the organization. To restore the user's access, re-add them to your organization. See [Create user](#create-user-request-multi-tenant). In Multi-tenant Cloud, a user's account is not managed by the organization.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Deactivating a service account is not supported. Manage team service accounts in the settings for the W\&B Team.<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `id`      | string | Yes      | The unique ID of the user to deactivate |
| `op`      | string | Yes      | `replace`                               |
| `value`   | object | Yes      | Object with `{"active": false}`         |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Deactivate User Request (Dedicated/Self-Managed)"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "value": {"active": false}
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Deactivate User Request (Multi-tenant)"></span>
```bash
    PATCH /scim/Users
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "value": {"active": false}
            }
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

#### Response

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Deactivate User Response (Dedicated/Self-Managed)"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": false,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Deactivate User Response (Multi-tenant)"></span>
```bash
    (Status 200)
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "value": {"active": true}
            }
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Reactivate User

Reactivates a previously deactivated user in your organization.

<span class="callout-start" data-callout-type="note"></span>
  * User reactivation works for users only, not service accounts. Reactivation is not supported for service accounts. Manage service accounts in the settings for the W\&B Team.

  * User reactivation is not supported in [Multi-tenant Cloud](/platform/hosting/hosting-options/multi_tenant_cloud). To restore the user's access, re-add them to your organization. See [Create user](#create-user-request-multi-tenant). In Multi-tenant Cloud, a user's account is not managed by the organization. An attempt to reactivate a user results in a HTTP `400` error:
```json
    {
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:Error"
        ],
        "detail": "User reactivation operations are not supported in SaaS Cloud",
        "status": "400"
    }
    ```
<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                             |
| --------- | ------ | -------- | --------------------------------------- |
| `id`      | string | Yes      | The unique ID of the user to reactivate |
| `op`      | string | Yes      | `replace`                               |
| `value`   | object | Yes      | Object with `{"active": true}`          |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Reactivate User Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "value": {"active": true}
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Reactivate User Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Assign Organization Role

Assigns an organization-level role to a user.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Custom roles are not supported for service accounts.<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                     |
| --------- | ------ | -------- | ------------------------------- |
| `id`      | string | Yes      | The unique ID of the user       |
| `op`      | string | Yes      | `replace`                       |
| `path`    | string | Yes      | `organizationRole`              |
| `value`   | string | Yes      | Role name (`admin` or `member`) |

<span class="callout-start" data-callout-type="note"></span>
  The organization-scoped `viewer` role is deprecated and can no longer be assigned in the UI. If you use SCIM to assign the `viewer` role to a user:

  * They are assigned the `member` role in the organization.
  * They are assigned a Models `viewer` seat, instead of a `full` seat. This allows view-only access to Models and full access to Registry. If no Models seats are available, a `Seat limit reached` error is logged and the member is added with no Models access. This can be updated later if a seat is available.
  * They are assigned a Weave `viewer` seat, instead of a `full` seat. This allows view-only access to Weave. If no Weave seats are available, a `Seat limit reached` error is logged and the member is added with no Weave access. This can be updated later if a seat is available.
  * They are assigned the Registry `viewer` role in registries that are visible at the organization level.
<span class="callout-end"></span>

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Assign Org Role Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "organizationRole",
                "value": "admin"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Assign Org Role Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1",
        "teamRoles": [
            {
                "teamName": "team1",
                "roleName": "admin"
            }
        ],
        "organizationRole": "admin"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Assign Team Role

Assigns a team-level role to a user.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Custom roles are not supported for service accounts.<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `id`      | string | Yes      | The unique ID of the user                       |
| `op`      | string | Yes      | `replace`                                       |
| `path`    | string | Yes      | `teamRoles`                                     |
| `value`   | array  | Yes      | Array of objects with `teamName` and `roleName` |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Assign Team Role Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "teamRoles",
                "value": [
                    {
                        "roleName": "admin",
                        "teamName": "team1"
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Assign Team Role Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1",
        "teamRoles": [
            {
                "teamName": "team1",
                "roleName": "admin"
            }
        ],
        "organizationRole": "admin"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Add to Registry

Adds a user to a registry with an assigned registry-level role.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Custom roles are not supported for service accounts.<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                                         |
| --------- | ------ | -------- | --------------------------------------------------- |
| `id`      | string | Yes      | The unique ID of the user                           |
| `op`      | string | Yes      | `add`                                               |
| `path`    | string | Yes      | `registryRoles`                                     |
| `value`   | array  | Yes      | Array of objects with `registryName` and `roleName` |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Add to Registry Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "registryRoles",
                "value": [
                    {
                        "roleName": "admin",
                        "registryName": "hello-registry"
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Add to Registry Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1",
        "registryRoles": [
            {
                "registryName": "hello-registry",
                "roleName": "admin"
            }
        ],
        "organizationRole": "admin"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Remove from Registry

Removes a user from a registry.

<span class="callout-start" data-callout-type="note"></span>
  * The remove operations follow RFC 7644 SCIM protocol specifications. Use the filter syntax `"registryRoles[registryName eq \"{registry_name}\"]"` to remove a user from a specific registry, or `"registryRoles"` to remove the user from all registries.
  * This operation works for users only, not service accounts. Remove service accounts from a registry in the settings for the W\&B Team.
<span class="callout-end"></span>

#### Endpoint

* **URL**: `<host-url>/scim/Users/{id}`
* **Method**: PATCH

#### Parameters

| Parameter | Type   | Required | Description                                                                 |
| --------- | ------ | -------- | --------------------------------------------------------------------------- |
| `id`      | string | Yes      | The unique ID of the user                                                   |
| `op`      | string | Yes      | `remove`                                                                    |
| `path`    | string | Yes      | `"registryRoles[registryName eq \"{registry_name}\"]"` or `"registryRoles"` |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Remove from Registry Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "registryRoles[registryName eq \"goodbye-registry\"]"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Remove from Registry Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1",
        "registryRoles": [
            {
                "registryName": "hello-registry",
                "roleName": "admin"
            }
        ],
        "organizationRole": "admin"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Remove from ALL Registries Request"></span>
```bash
    PATCH /scim/Users/abc
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "replace",
                "path": "registryRoles"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Remove from ALL Registries Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "active": true,
        "displayName": "Dev User 1",
        "emails": {
            "Value": "dev-user1@example.com",
            "Display": "",
            "Type": "",
            "Primary": true
        },
        "id": "abc",
        "meta": {
            "resourceType": "User",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Users/abc"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:User"
        ],
        "userName": "dev-user1",
        "organizationRole": "admin"
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

## Group resource

When you create a SCIM group in your IAM, it creates and maps to a W\&B Team, and other SCIM group operations operate on the team.

### Service Accounts

When a W\&B Team is created using SCIM, all organization-level service accounts are automatically added to the team, to maintain the service account's access to team resources.

### Filtering Groups

The `/Groups` endpoint supports filtering to search for specific teams:

#### Supported Filters

* `displayName eq "value"` - Filter by team display name

#### Example

```bash
GET /scim/Groups?filter=displayName eq "engineering-team"

Get team#

Retrieve team information by providing the team’s unique ID.

Endpoint#

  • URL: <host-url>/scim/Groups/{id}
  • Method: GET

Example#

    GET /scim/Groups/ghi
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "displayName": "acme-devs",
        "id": "ghi",
        "members": [
            {
                "Value": "abc",
                "Ref": "",
                "Type": "",
                "Display": "dev-user1"
            }
        ],
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Groups/ghi"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### List teams

Retrieve a list of teams.

#### Endpoint

* **URL**: `<host-url>/scim/Groups`
* **Method**: GET

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    GET /scim/Groups
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "Resources": [
            {
                "displayName": "acme-devs",
                "id": "ghi",
                "members": [
                    {
                        "Value": "abc",
                        "Ref": "",
                        "Type": "",
                        "Display": "dev-user1"
                    }
                ],
                "meta": {
                    "resourceType": "Group",
                    "created": "2023-10-01T00:00:00Z",
                    "lastModified": "2023-10-01T00:00:00Z",
                    "location": "Groups/ghi"
                },
                "schemas": [
                    "urn:ietf:params:scim:schemas:core:2.0:Group"
                ]
            }
        ],
        "itemsPerPage": 9999,
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "startIndex": 1,
        "totalResults": 1
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Create team

* **Endpoint**: **`<host-url>/scim/Groups`**
* **Method**: POST
* **Description**: Create a new team resource.
* **Supported Fields**:

| Field         | Type               | Required                                                  |
| ------------- | ------------------ | --------------------------------------------------------- |
| `displayName` | String             | Yes                                                       |
| `members`     | Multi-Valued Array | Yes (`value` sub-field is required and maps to a user ID) |

#### Example

Creating a team called `wandb-support` with `dev-user2` as its member.

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    POST /scim/Groups
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "displayName": "wandb-support",
        "members": [
            {
                "value": "def"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 201)
    ```

```json
    {
        "displayName": "wandb-support",
        "id": "jkl",
        "members": [
            {
                "Value": "def",
                "Ref": "",
                "Type": "",
                "Display": "dev-user2"
            }
        ],
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:00:00Z",
            "location": "Groups/jkl"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Update team

* **Endpoint**: **`<host-url>/scim/Groups/{id}`**
* **Method**: PATCH
* **Description**: Update an existing team's membership list.
* **Supported Operations**: `add` member, `remove` member, `replace` members

<span class="callout-start" data-callout-type="note"></span>
  - The remove operations follow RFC 7644 SCIM protocol specifications. Use the filter syntax `members[value eq "{user_id}"]` to remove a specific user, or `members` to remove all users from the team.

**User Identification**: The `{user_id}` in member operations can be either:

* A W\&B user ID
* An email address (e.g., "[user@example.com](mailto:user@example.com)")
  - These operations work for users only, not service accounts. Update a team's service accounts in the settings for the W\&B Team.
<span class="callout-end"></span>

<span class="callout-start" data-callout-type="info"></span>
  Replace `{team_id}` with the actual team ID and `{user_id}` with the actual user ID or email address in your requests.
<span class="callout-end"></span>

### Replace team members

Replaces all members of a team with a new list.

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Manage service accounts in the settings for the W\&B Team.<span class="callout-end"></span>

* **Endpoint**: **`<host-url>/scim/Groups/{id}`**
* **Method**: PUT
* **Description**: Replace the entire team membership list.

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PUT /scim/Groups/{team_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
        "displayName": "acme-devs",
        "members": [
            {
                "value": "{user_id_1}"
            },
            {
                "value": "{user_id_2}"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "displayName": "acme-devs",
        "id": "ghi",
        "members": [
            {
                "Value": "user_id_1",
                "Ref": "",
                "Type": "",
                "Display": "user1"
            },
            {
                "Value": "user_id_2",
                "Ref": "",
                "Type": "",
                "Display": "user2"
            }
        ],
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:01:00Z",
            "location": "Groups/ghi"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

**Adding a user to a team**

Adding `dev-user2` to `acme-devs`:

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Manage service accounts in the settings for the W\&B Team.<span class="callout-end"></span>

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PATCH /scim/Groups/{team_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "add",
                "path": "members",
                "value": [
                    {
                        "value": "{user_id}"
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "displayName": "acme-devs",
        "id": "ghi",
        "members": [
            {
                "Value": "abc",
                "Ref": "",
                "Type": "",
                "Display": "dev-user1"
            },
            {
                "Value": "def",
                "Ref": "",
                "Type": "",
                "Display": "dev-user2"
            }
        ],
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:01:00Z",
            "location": "Groups/ghi"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

**Removing a specific user from a team**

Removing `dev-user2` from `acme-devs`:

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Manage service accounts in the settings for the W\&B Team.<span class="callout-end"></span>

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PATCH /scim/Groups/{team_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "remove",
                "path": "members[value eq \"{user_id}\"]"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "displayName": "acme-devs",
        "id": "ghi",
        "members": [
            {
                "Value": "abc",
                "Display": "dev-user1"
            }
        ],
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:01:00Z",
            "location": "Groups/ghi"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

**Removing all users from a team**

Removing all users from `acme-devs`:

<span class="callout-start" data-callout-type="note"></span>This operation works for users only, not service accounts. Manage service accounts in the settings for the W\&B Team.<span class="callout-end"></span>

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PATCH /scim/Groups/{team_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "remove",
                "path": "members"
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "displayName": "acme-devs",
        "id": "ghi",
        "members": null,
        "meta": {
            "resourceType": "Group",
            "created": "2023-10-01T00:00:00Z",
            "lastModified": "2023-10-01T00:01:00Z",
            "location": "Groups/ghi"
        },
        "schemas": [
            "urn:ietf:params:scim:schemas:core:2.0:Group"
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Delete team

* Deleting teams is currently unsupported by the SCIM API since there is additional data linked to teams. Delete teams from the app to confirm you want everything deleted.

## Role resource

The SCIM role resource maps to W\&B custom roles. As mentioned earlier, the `/Roles` endpoints are not part of the official SCIM schema, W\&B adds `/Roles` endpoints to support automated management of custom roles in W\&B organizations.

### Get custom role

Retrieve information for a custom role by providing the role's unique ID.

#### Endpoint

* **URL**: `<host-url>/scim/Roles/{id}`
* **Method**: GET

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    GET /scim/Roles/abc
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
        "description": "A sample custom role for example",
        "id": "Um9sZTo3",
        "inheritedFrom": "member", // indicates the predefined role
        "meta": {
            "resourceType": "Role",
            "created": "2023-11-20T23:10:14Z",
            "lastModified": "2023-11-20T23:31:23Z",
            "location": "Roles/Um9sZTo3"
        },
        "name": "Sample custom role",
        "organizationID": "T3JnYW5pemF0aW9uOjE0ODQ1OA==",
        "permissions": [
            {
                "name": "artifact:read",
                "isInherited": true // inherited from member predefined role
            },
            ...
            ...
            {
                "name": "project:update",
                "isInherited": false // custom permission added by admin
            }
        ],
        "schemas": [
            ""
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### List custom roles

Retrieve information for all custom roles in the W\&B organization.

#### Endpoint

* **URL**: `<host-url>/scim/Roles`
* **Method**: GET

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    GET /scim/Roles
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

```json
    {
       "Resources": [
            {
                "description": "A sample custom role for example",
                "id": "Um9sZTo3",
                "inheritedFrom": "member", // indicates the predefined role that the custom role inherits from
                "meta": {
                    "resourceType": "Role",
                    "created": "2023-11-20T23:10:14Z",
                    "lastModified": "2023-11-20T23:31:23Z",
                    "location": "Roles/Um9sZTo3"
                },
                "name": "Sample custom role",
                "organizationID": "T3JnYW5pemF0aW9uOjE0ODQ1OA==",
                "permissions": [
                    {
                        "name": "artifact:read",
                        "isInherited": true // inherited from member predefined role
                    },
                    ...
                    ...
                    {
                        "name": "project:update",
                        "isInherited": false // custom permission added by admin
                    }
                ],
                "schemas": [
                    ""
                ]
            },
            {
                "description": "Another sample custom role for example",
                "id": "Um9sZToxMg==",
                "inheritedFrom": "viewer", // indicates the predefined role that the custom role inherits from
                "meta": {
                    "resourceType": "Role",
                    "created": "2023-11-21T01:07:50Z",
                    "location": "Roles/Um9sZToxMg=="
                },
                "name": "Sample custom role 2",
                "organizationID": "T3JnYW5pemF0aW9uOjE0ODQ1OA==",
                "permissions": [
                    {
                        "name": "launchagent:read",
                        "isInherited": true // inherited from viewer predefined role
                    },
                    ...
                    ...
                    {
                        "name": "run:stop",
                        "isInherited": false // custom permission added by admin
                    }
                ],
                "schemas": [
                    ""
                ]
            }
        ],
        "itemsPerPage": 9999,
        "schemas": [
            "urn:ietf:params:scim:api:messages:2.0:ListResponse"
        ],
        "startIndex": 1,
        "totalResults": 2
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Create custom role

* **Endpoint**: **`<host-url>/scim/Roles`**
* **Method**: POST
* **Description**: Create a new custom role in the W\&B organization.
* **Supported Fields**:

| Field           | Type         | Required                                                                                                                                                                                                                             |
| --------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name`          | String       | Name of the custom role                                                                                                                                                                                                              |
| `description`   | String       | Description of the custom role                                                                                                                                                                                                       |
| `permissions`   | Object array | Array of permission objects where each object includes a `name` string field that has value of the form `w&bobject:operation`. For example, a permission object for delete operation on W\&B runs would have `name` as `run:delete`. |
| `inheritedFrom` | String       | The predefined role which the custom role would inherit from. It can either be `member` or `viewer`.                                                                                                                                 |

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    POST /scim/Roles
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Role"],
        "name": "Sample custom role",
        "description": "A sample custom role for example",
        "permissions": [
            {
                "name": "project:update"
            }
        ],
        "inheritedFrom": "member"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 201)
    ```

```json
    {
        "description": "A sample custom role for example",
        "id": "Um9sZTo3",
        "inheritedFrom": "member", // indicates the predefined role
        "meta": {
            "resourceType": "Role",
            "created": "2023-11-20T23:10:14Z",
            "lastModified": "2023-11-20T23:31:23Z",
            "location": "Roles/Um9sZTo3"
        },
        "name": "Sample custom role",
        "organizationID": "T3JnYW5pemF0aW9uOjE0ODQ1OA==",
        "permissions": [
            {
                "name": "artifact:read",
                "isInherited": true // inherited from member predefined role
            },
            ...
            ...
            {
                "name": "project:update",
                "isInherited": false // custom permission added by admin
            }
        ],
        "schemas": [
            ""
        ]
    }
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Update custom role

#### Add permissions to role

* **Endpoint**: **`<host-url>/scim/Roles/{id}`**
* **Method**: PATCH
* **Description**: Add permissions to an existing custom role.

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PATCH /scim/Roles/{role_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "add",
                "path": "permissions",
                "value": [
                    {
                        "name": "project:delete"
                    },
                    {
                        "name": "run:stop"
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

Returns the updated role with new permissions added.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

#### Remove a permission from a role

* **Endpoint**: **`<host-url>/scim/Roles/{id}`**
* **Method**: PATCH
* **Description**: Remove permissions from an existing custom role.

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PATCH /scim/Roles/{role_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
        "Operations": [
            {
                "op": "remove",
                "path": "permissions",
                "value": [
                    {
                        "name": "project:update"
                    }
                ]
            }
        ]
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

Returns the updated role with specified permissions removed.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Replace custom role

* **Endpoint**: **`<host-url>/scim/Roles/{id}`**
* **Method**: PUT
* **Description**: Replace an entire custom role definition.

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    PUT /scim/Roles/{role_id}
    ```

```json
    {
        "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Role"],
        "name": "Updated custom role",
        "description": "Updated description for the custom role",
        "permissions": [
            {
                "name": "project:read"
            },
            {
                "name": "run:read"
            },
            {
                "name": "artifact:read"
            }
        ],
        "inheritedFrom": "viewer"
    }
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 200)
    ```

Returns the completely replaced role definition.
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

### Delete custom role

Delete a custom role in the W\&B organization. **Use it with caution**. The predefined role from which the custom role inherited is now assigned to all users that were assigned the custom role before the operation.

#### Endpoint

* **URL**: `<host-url>/scim/Roles/{id}`
* **Method**: DELETE

#### Example

<span class="tab-group-start"></span>
  <span class="tab-start" data-tab-title="Request"></span>
```bash
    DELETE /scim/Roles/abc
    ```
  <span class="tab-end"></span>

  <span class="tab-start" data-tab-title="Response"></span>
```bash
    (Status 204 No Content)
    ```
  <span class="tab-end"></span>
<span class="tab-group-end"></span>

## Advanced Features

### ETag Support

The SCIM API supports ETags for conditional updates to prevent concurrent modification conflicts. ETags are returned in the `ETag` response header and the `meta.version` field.

#### ETags

To use Etags:

1. **Get current ETag**: When you GET a resource, note the ETag header in the response
2. **Conditional update**: Include the ETag in the `If-Match` header when updating

#### Example

Get user and note ETag#

GET /scim/Users/abc

Response includes: ETag: W/“xyz123”#

Update with ETag#

PATCH /scim/Users/abc If-Match: W/“xyz123”

{ “schemas”: [“urn:ietf:params:scim:api:messages:2.0:PatchOp”], “Operations”: [ { “op”: “replace”, “path”: “organizationRole”, “value”: “admin” } ] }


A `412 Precondition Failed` error response indicates that the resources has been modified since you retrieved it.

### Error handling

The SCIM API returns standard SCIM error responses:

| Status Code | Description                                      |
| ----------- | ------------------------------------------------ |
| `200`       | Success                                          |
| `201`       | Created                                          |
| `204`       | No Content (successful deletion)                 |
| `400`       | Bad Request - Invalid parameters or request body |
| `401`       | Unauthorized - Authentication failed             |
| `403`       | Forbidden - Insufficient permissions             |
| `404`       | Not Found - Resource does not exist              |
| `409`       | Conflict - Resource already exists               |
| `412`       | Precondition Failed - ETag mismatch              |
| `500`       | Internal Server Error                            |

### Implementation differences per deployment type

W\&B maintains two separate SCIM API implementations, and the features differ between them:

| Feature                  | Dedicated Cloud | Self-Managed |
| ------------------------ | --------------- | ------------ |
| Update user email        | -               | ✓            |
| Update user display name | -               | ✓            |
| User deactivation        | ✓               | ✓            |
| User reactivation        | -               | ✓            |
| Multiple emails per user | ✓               | -            |

## Limitations

* **Maximum results**: 9999 items per request.
* **Single-tenant environments**: Only support one email per user.
* **Team deletion**: Not supported via SCIM (use the W\&B web interface).
* **User reactivation**: Not supported in Multi-tenant Cloud environments.
* **Seat limits**: Operations may fail if organization seat limits are reached.
Link last verified June 7, 2026. View original ↗
Source: Weights & Biases Docs
Link last verified: 2026-03-04