Skip to main content

SCIM

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.

The SCIM API is accessible at <host-url>/scim/ and supports the /Users and /Groups endpoints with a subset of the fields found in the RC7643 protocol. It additionally includes the /Roles endpoints which are not part of the official SCIM schema. W&B adds the /Roles endpoints to support automated management of custom roles in W&B organizations.

info

SCIM API applies to all hosting options including Dedicated Cloud, Self-managed deployment and SaaS Cloud. In SaaS Cloud, the organization admin must configure the default organization in user settings to ensure that the SCIM API requests go to the right organization. The setting is available in the section SCIM API Organization.

Authentication

The SCIM API is accessible by instance or organization admins using basic authentication with their API key. With basic authentication, send the HTTP request with the Authorization header that contains the word Basic followed by a space and a base64-encoded string for username:password where password is your API key. For example, to authorize as demo:p@55w0rd, the header should be Authorization: Basic ZGVtbzpwQDU1dzByZA==.

User resource

The SCIM user resource maps to W&B users.

Get user

  • Endpoint: <host-url>/scim/Users/{id}
  • Method: GET
  • Description: Retrieve user information by providing the user's unique ID.
  • Request Example:
GET /scim/Users/abc
  • Response Example:
(Status 200)
{
"active": true,
"emails": {
"Value": "dev-user1@test.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

  • Endpoint: <host-url>/scim/Users
  • Method: GET
  • Description: Retrieve a list of users.
  • Request Example:
GET /scim/Users
  • Response Example:
(Status 200)
{
"Resources": [
{
"active": true,
"emails": {
"Value": "dev-user1@test.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

  • Endpoint: <host-url>/scim/Users
  • Method: POST
  • Description: Create a new user resource.
  • Supported Fields:
FieldTypeRequired
emailsMulti-Valued ArrayYes (Make sure primary email is set)
userNameStringYes
  • Request Example:
POST /scim/Users
{
"schemas": [
"urn:ietf:params:scim:schemas:core:2.0:User"
],
"emails": [
{
"primary": true,
"value": "admin-user2@test.com"
}
],
"userName": "dev-user2"
}
  • Response Example:
(Status 201)
{
"active": true,
"emails": {
"Value": "dev-user2@test.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"
}

Deactivate user

  • Endpoint: <host-url>/scim/Users/{id}
  • Method: DELETE
  • Description: Deactivate a user by providing the user's unique ID.
  • Request Example:
DELETE /scim/Users/abc
  • Response Example:
(Status 204)

Reactivate user

  • Reactivating a previously deactivated user is currently unsupported in the SCIM API.

Group resource

The SCIM group resource maps to W&B teams, that is, when you create a SCIM group in a W&B deployment, it creates a W&B team. Same applies to other group endpoints.

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": "wandb-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": "wandb-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:
FieldTypeRequired
displayNameStringYes
membersMulti-Valued ArrayYes (value sub-field is required and maps to a user ID)
  • 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
  • Request Example:

Adding dev-user2 to wandb-devs

PATCH /scim/Groups/ghi
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "add",
"path": "members",
"value": [
{
"value": "def",
}
]
}
]
}
  • Response Example:
(Status 200)
{
"displayName": "wandb-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"
]
}

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:
FieldTypeRequired
nameStringName of the custom role
descriptionStringDescription of the custom role
permissionsObject arrayArray 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.
inheritedFromStringThe predefined role which the custom role would inherit from. It can either be member or viewer.
  • 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": [
""
]
}

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
  • Response Example:
(Status 204)

Update custom role permissions

  • Endpoint: <host-url>/scim/Roles/{id}
  • Method: PATCH
  • Description: Add or remove custom permissions in a custom role in the W&B organization.
  • Supported Fields:
FieldTypeRequired
operationsObject arrayArray of operation objects
opStringType of operation within the operation object. It can either be add or remove.
pathStringStatic field in the operation object. Only value allowed is permissions.
valueObject arrayArray 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.
  • Request Example:
caution

The request path for the update custom role permissions API is same as for role assignment APIs, that is, the PATCH - Assign organization-level role to user and PATCH - Assign team-level role to user operations. Difference is that the URI for custom role APIs expects a :roleId parameter, while the URI for role assignment APIs expects a :userId. Expected request bodies for both types of APIs are also different.

Be careful with the parameter value in the URI and the request body such that those map to the intended operation.

PATCH /scim/Roles/abc
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "add", // indicates the type of operation, other possible value being `remove`
"path": "permissions",
"value": [
{
"name": "project:delete"
}
]
}
]
}
  • 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 // existing custom permission added by admin before the update
},
{
"name": "project:delete",
"isInherited": false // new custom permission added by admin as part of the update
}
],
"schemas": [
""
]
}

Update custom role metadata

  • Endpoint: <host-url>/scim/Roles/{id}
  • Method: PUT
  • Description: Update the name, description or inherited role for a custom role in the W&B organization. This operation doesn't affect any of the existing, that is, non-inherited custom permissions in the custom role.
  • Supported Fields:
FieldTypeRequired
nameStringName of the custom role
descriptionStringDescription of the custom role
inheritedFromStringThe predefined role which the custom role inherits from. It can either be member or viewer.
  • Request Example:
PUT /scim/Roles/abc
{
"schemas": ["urn:ietf:params:scim:schemas:core:2.0:Role"],
"name": "Sample custom role",
"description": "A sample custom role for example but now based on viewer",
"inheritedFrom": "viewer"
}
  • Response Example:
(Status 200)
{
"description": "A sample custom role for example but now based on viewer", // changed the descripton per the request
"id": "Um9sZTo3",
"inheritedFrom": "viewer", // indicates the predefined role which is changed per the request
"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 viewer predefined role
},
... // Any permissions that are in member predefined role but not in viewer will not be inherited post the update
{
"name": "project:update",
"isInherited": false // custom permission added by admin
},
{
"name": "project:delete",
"isInherited": false // custom permission added by admin
}
],
"schemas": [
""
]
}

Assign organization-level role to user

  • Endpoint: <host-url>/scim/Roles/{userId}
  • Method: PATCH
  • Description: Assign an organization-level role to a user. The role can be one of admin, viewer or member as described here. For Public Cloud, ensure that you have configured the correct organization for SCIM API in user settings.
  • Supported Fields:
FieldTypeRequired
opStringType of operation. The only allowed value is replace.
pathStringThe scope at which role assignment operation takes effect. The only allowed value is organizationRole.
valueStringThe predefined organization-level role to assign to the user. It can be one of admin, viewer or member. This field is case insensitive for predefined roles.
  • Request Example:
caution

The request path for the role assignment API is same as for custom role APIs, especially the PATCH - Update custom role permissions operation. Difference is that the URI for role assignment API expects a :userId parameter, while the URI for custom role API expects a :roleId. Expected request bodies for both APIs are also different.

Be careful with the parameter value in the URI and the request body such that those map to the intended operation.

PUT /scim/Roles/abc
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"path": "organizationRole",
"value": "admin" // will set the user's organization-scoped role to admin
}
]
}
  • Response Example: This returns a User object, like in case of user resource.
(Status 200)
{
"active": true,
"emails": {
"Value": "dev-user1@test.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": [ // Returns the user's roles in all the teams that they are a part of
{
"teamName": "team1",
"roleName": "admin"
}
],
"organizationRole": "admin" // Returns the user's role at the organization scope
}

Assign team-level role to user

  • Endpoint: <host-url>/scim/Roles/{userId}
  • Method: PATCH
  • Description: Assign a team-level role to a user. The role can be one of admin, viewer, member or a custom role as described here. For Public Cloud, ensure that you have configured the correct organization for SCIM API in user settings.
  • Supported Fields:
FieldTypeRequired
opStringType of operation. The only allowed value is replace.
pathStringThe scope at which role assignment operation takes effect. The only allowed value is teamRoles.
valueObject arrayA one-object array where the object consists of teamName and roleName attributes. The teamName is the name of the team where the user holds the role, and roleName can be one of admin, viewer, member or a custom role. This field is case insensitive for predefined roles and case sensitive for custom roles.
  • Request Example:
caution

The request path for the role assignment API is same as for custom role APIs, especially the PATCH - Update custom role permissions operation. Difference is that the URI for role assignment API expects a :userId parameter, while the URI for custom role API expects a :roleId. Expected request bodies for both APIs are also different.

Be careful with the parameter value in the URI and the request body such that those map to the intended operation.

PUT /scim/Roles/abc
{
"schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"],
"Operations": [
{
"op": "replace",
"path": "teamRoles",
"value": [
{
"roleName": "admin", // role name is case insensitive for predefined roles and case sensitive for custom roles
"teamName": "team1" // will set the user's role in the team team1 to admin
}
]
}
]
}
  • Response Example: This returns a User object, like in case of user resource.
(Status 200)
{
"active": true,
"emails": {
"Value": "dev-user1@test.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": [ // Returns the user's roles in all the teams that they are a part of
{
"teamName": "team1",
"roleName": "admin"
}
],
"organizationRole": "admin" // Returns the user's role at the organization scope
}
Was this page helpful?👍👎