Manage users, groups, and roles with SCIM

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

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.
• SaaS Cloud org targeting: For multi-org admins, set the Default API organization to ensure requests affect the intended org.

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.

Endpoint

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

Parameters

Example

• Get User Request
• Get User Response

GET /scim/Users/abc

(Status 200)

{
    "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"
}

List users

Retrieves a list of all users in your organization.

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

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

• List Users Request
• List Users Response

GET /scim/Users

(Status 200)

{
    "Resources": [
        {
            "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"
        }
    ],
    "itemsPerPage": 9999,
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:ListResponse"
    ],
    "startIndex": 1,
    "totalResults": 1
}

Create User

Creates a new user in your organization.

Endpoint

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

Parameters

Example

• Create User Request (Dedicated/Self-managed)
• Create User Request (Multi-tenant)

POST /scim/Users

{
    "schemas": [
        "urn:ietf:params:scim:schemas:core:2.0:User"
    ],
    "emails": [
        {
            "primary": true,
            "value": "dev-user2@example.com"
        }
    ],
    "userName": "dev-user2"
}

POST /scim/Users

{
    "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"]
    }
}

Response

• Create User Response (Dedicated/Self-managed)
• Create User Response (Multi-tenant)

(Status 201)

{
    "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"
}

(Status 201)

{
    "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"
        }
    ]
}

Delete User

Fully deletes a user from your organization.

Endpoint

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

Parameters

Example

• Delete User Request
• Delete User Response

DELETE /scim/Users/abc

(Status 204)

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

Example

• Update Email Request
• Update Email Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "emails",
            "value": [
                {
                    "value": "newemail@example.com",
                    "primary": true
                }
            ]
        }
    ]
}

(Status 200)

{
    "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"
}

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

Example

• Update Display Name Request
• Update Display Name Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "displayName",
            "value": "John Doe"
        }
    ]
}

(Status 200)

{
    "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"
}

Deactivate user

Deactivates a user in your organization.

Endpoint

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

Parameters

Example

• Deactivate User Request
• Deactivate User Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "value": {"active": false}
        }
    ]
}

(Status 200)

{
    "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"
}

Reactivate User

Reactivates a previously deactivated user in your organization.

Endpoint

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

Parameters

Example

• Reactivate User Request
• Reactivate User Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "value": {"active": true}
        }
    ]
}

(Status 200)

{
    "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"
}

Assign Organization Role

Assigns an organization-level role to a user.

Endpoint

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

Parameters

Example

• Assign Org Role Request
• Assign Org Role Response

PATCH /scim/Users/abc

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

(Status 200)

{
    "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"
}

Assign Team Role

Assigns a team-level role to a user.

Endpoint

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

Parameters

Example

• Assign Team Role Request
• Assign Team Role Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "teamRoles",
            "value": [
                {
                    "roleName": "admin",
                    "teamName": "team1"
                }
            ]
        }
    ]
}

(Status 200)

{
    "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"
}

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

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

Get team

• Endpoint: <host-url>/scim/Groups/{id}
• Method: GET
• Description: Retrieve team information by providing the team’s unique ID.
• Request Example:

GET /scim/Groups/ghi

• Response Example:

(Status 200)

{
    "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"
    ]
}

List teams

• Endpoint: <host-url>/scim/Groups
• Method: GET
• Description: Retrieve a list of teams.
• Request Example:

GET /scim/Groups

• Response Example:

(Status 200)

{
    "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
}

Create team

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

• Request Example:

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

POST /scim/Groups

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "wandb-support",
    "members": [
        {
            "value": "def"
        }
    ]
}

• Response Example:

(Status 201)

{
    "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"
    ]
}

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

Replace team members

Replaces all members of a team with a new list.

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

• Request
• Response

PUT /scim/Groups/{team_id}

{
    "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
    "displayName": "acme-devs",
    "members": [
        {
            "value": "{user_id_1}"
        },
        {
            "value": "{user_id_2}"
        }
    ]
}

(Status 200)

{
    "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"
    ]
}

Adding a user to a team

Adding dev-user2 to acme-devs:

• Request
• Response

PATCH /scim/Groups/{team_id}

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "add",
            "path": "members",
            "value": [
                {
                    "value": "{user_id}"
                }
            ]
        }
    ]
}

(Status 200)

{
    "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"
    ]
}

Removing a specific user from a team

Removing dev-user2 from acme-devs:

• Request
• Response

PATCH /scim/Groups/{team_id}

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "remove",
            "path": "members[value eq \"{user_id}\"]"
        }
    ]
}

(Status 200)

{
    "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"
    ]
}

Removing all users from a team

Removing all users from acme-devs:

• Request
• Response

PATCH /scim/Groups/{team_id}

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "remove",
            "path": "members"
        }
    ]
}

(Status 200)

{
    "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"
    ]
}

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

• Endpoint: <host-url>/scim/Roles/{id}
• Method: GET
• Description: Retrieve information for a custom role by providing the role’s unique ID.
• Request Example:

GET /scim/Roles/abc

• Response Example:

(Status 200)

{
    "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": [
        ""
    ]
}

List custom roles

• Endpoint: <host-url>/scim/Roles
• Method: GET
• Description: Retrieve information for all custom roles in the W&B organization
• Request Example:

GET /scim/Roles

• Response Example:

(Status 200)

{
   "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
}

Create custom role

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

• Request Example:

POST /scim/Roles

{
    "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"
}

• Response Example:

(Status 201)

{
    "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": [
        ""
    ]
}

Update custom role

Add permissions to role

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

• Request
• Response

PATCH /scim/Roles/{role_id}

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "add",
            "path": "permissions",
            "value": [
                {
                    "name": "project:delete"
                },
                {
                    "name": "run:stop"
                }
            ]
        }
    ]
}

(Status 200)

Remove a permission from a role

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

• Request
• Response

PATCH /scim/Roles/{role_id}

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "remove",
            "path": "permissions",
            "value": [
                {
                    "name": "project:update"
                }
            ]
        }
    ]
}

(Status 200)

Replace custom role

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

• Request
• Response

PUT /scim/Roles/{role_id}

{
    "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"
}

(Status 200)

Delete custom role

• Endpoint: <host-url>/scim/Roles/{id}
• Method: DELETE
• Description: 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.
• Request Example:

DELETE /scim/Roles/abc

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:

Implementation differences per deployment type

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

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 deactivation/reactivation: Not supported in SaaS Cloud environments
• Seat limits: Operations may fail if organization seat limits are reached