Manage users, groups, and roles with SCIM - Weights & Biases Documentation

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.

Endpoint

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

Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique ID of the user

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

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

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

Maintain admin accessYou 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.

Fully deletes a user from your organization.

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

Delete User Request
Delete User Response

DELETE /scim/Users/abc

(Status 204)

To temporarily deactivate the user, refer to Deactivate user API which uses the PATCH endpoint.

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

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

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

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. 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.
Multi-tenant Cloud: Removes the user from the organization. To restore the user’s access, re-add them to your organization. See Create user. In Multi-tenant Cloud, 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 to deactivate
`op`	string	Yes	`replace`
`value`	object	Yes	Object with `{"active": false}`

Example

Deactivate User Request (Dedicated/Self-Managed)
Deactivate User Request (Multi-tenant)

PATCH /scim/Users/abc

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

PATCH /scim/Users

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

Response

Deactivate User Response (Dedicated/Self-Managed)
Deactivate User Response (Multi-tenant)

(Status 200)

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

(Status 200)

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

Reactivate User

Reactivates a previously deactivated user in your organization.

User reactivation is not supported in Multi-tenant Cloud. To restore the user’s access, re-add them to your organization. See Create user. 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:

{
    "schemas": [
        "urn:ietf:params:scim:api:messages:2.0:Error"
    ],
    "detail": "User reactivation operations are not supported in SaaS Cloud",
    "status": "400"
}

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

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

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`)

The viewer role is deprecated and can no longer be set in the UI. W&B assigns the member role to a user if you attempt to assign the viewer role using SCIM. The user is automatically provisioned with Models and Weave seats if possible. Otherwise, a Seat limit reached error is logged. For organizations that use Registry, the user is automatically assigned the viewer role in registries that are visible at the organization level.

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

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

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

Add to Registry

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

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

Add to Registry Request
Add to Registry Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "registryRoles",
            "value": [
                {
                    "roleName": "admin",
                    "registryName": "hello-registry"
                }
            ]
        }
    ]
}

(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",
    "registryRoles": [
        {
            "registryName": "hello-registry",
            "roleName": "admin"
        }
    ],
    "organizationRole": "admin"
}

Remove from Registry

Removes a user from a registry.

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.

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

Remove from Registry Request
Remove from Registry Response

PATCH /scim/Users/abc

{
    "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
    "Operations": [
        {
            "op": "replace",
            "path": "registryRoles[registryName eq \"goodbye-registry\"]"
        }
    ]
}

(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",
    "registryRoles": [
        {
            "registryName": "hello-registry",
            "roleName": "admin"
        }
    ],
    "organizationRole": "admin"
}

Remove from ALL Registries Request
Remove from ALL Registries Response

PATCH /scim/Users/abc

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

(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",
    "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

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

Endpoint

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

Example

Request
Response

GET /scim/Groups/ghi

(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

Retrieve a list of teams.

Endpoint

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

Example

Request
Response

GET /scim/Groups

(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:

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.

Request
Response

POST /scim/Groups

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

(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

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”)

Replace {team_id} with the actual team ID and {user_id} with the actual user ID or email address in your requests.

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

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

Endpoint

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

Example

Request
Response

GET /scim/Roles/abc

(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

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

Endpoint

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

Example

Request
Response

GET /scim/Roles

(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:

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

Request
Response

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

(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)

Returns the updated role with new permissions added.

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)

Returns the updated role with specified permissions removed.

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)

Returns the completely replaced role definition.

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

Request
Response

DELETE /scim/Roles/abc

(Status 204 No Content)

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:

Get current ETag: When you GET a resource, note the ETag header in the response
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.

​Overview

​Supported Features

​Authentication

​Key differences

​Users

​Service accounts

​User management

​Get user

​Endpoint

​Parameters

​Example

​List users

​Filter users

Example

​Endpoint

​Example

​Create User

​Endpoint

​Parameters

​Example

​Response

​Delete User

​Endpoint

​Parameters

​Example

​Update user email

​Endpoint

​Parameters

​Example

​Update user display name

​Endpoint

​Parameters

​Example

​Deactivate user

​Endpoint

​Parameters

​Example

​Response

​Reactivate User

​Endpoint

​Parameters

​Example

​Assign Organization Role

​Endpoint

​Parameters

​Example

​Assign Team Role

​Endpoint

​Parameters

​Example

​Add to Registry

​Endpoint

​Parameters

​Example

​Remove from Registry

​Endpoint

​Parameters

​Example

​Group resource

​Service Accounts

​Filtering Groups

​Supported Filters

​Example

​Get team

​Endpoint

​Example

​List teams

​Endpoint

​Example

​Create team

​Example

​Update team

​Replace team members

​Delete team

​Role resource

​Get custom role

​Endpoint

​Example

​List custom roles

​Endpoint

Overview

Supported Features

Authentication

Key differences

Users

Service accounts

User management

Get user

Endpoint

Parameters

Example

List users

Filter users

Endpoint

Example

Create User

Endpoint

Parameters

Example

Response

Delete User

Endpoint

Parameters

Example

Update user email

Endpoint

Parameters

Example

Update user display name

Endpoint

Parameters

Example

Deactivate user

Endpoint

Parameters

Example

Response

Reactivate User

Endpoint

Parameters

Example

Assign Organization Role

Endpoint

Parameters

Example

Assign Team Role

Endpoint

Parameters

Example

Add to Registry

Endpoint

Parameters

Example

Remove from Registry

Endpoint

Parameters

Example

Group resource

Service Accounts

Filtering Groups

Supported Filters

Example

Get team

Endpoint

Example

List teams

Endpoint

Example

Create team

Example

Update team

Replace team members

Delete team

Role resource

Get custom role

Endpoint

Example

List custom roles

Endpoint

Example