The following diagram shows the state (status) transition process of a group containing users.
New
This is the initial status of a group. This status is assigned by the platform when the group is created.
Active
The group has been created successfully and is now active.
Deleted
The group has been deleted by the account administrator.
Delete a user group.
Updates a user group.
Gets a single user group by ID.
Gets the user groups collection.
Creates a user group for the client account.
The User Group object represents a group containing users.
This object contains the following attributes:
id
string, core
(Read-only) Primary identifier for the group.
icon
string
(Optional) The relative path to the group's icon image or logo.
name
string, core
The name of the group.
description
string
(Optional) A description of the group.
modules
object
(Optional) Represents the object, which contains modules that the group members can access.
default
bool
Indicates if the group has been set as a default group within the account. An account can contain only one default group.
users
object
(Read-only)Represents the object containing users assigned to the group. A group can be deleted only if no user is assigned.
{
"id": "UGR-5116-6265",
"name": "Jane Doe",
"description": "This group contains all Accounts team members",
"modules": [
{
"id": "MOD-1756-1452",
"name": "Access management"
},
{
"id": "MOD-9042-8216",
"name": "Account management"
}
],
"icon": "https://picsum.photos/210/201",
"default": true,
"users": [
{
"id": "USR-0000-0016",
"icon": null,
"name": "Reto Mayer"
}
]
}Delete user group. Permanently removes the user group; the group can be deleted only if no users are assigned. Returns 204 No Content on success.
User group identifier.
No Content
No content
Bad Request
Not Found
DELETE /public/v1/accounts/user-groups/{id} HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
No content
Update user group. Accepts a delta payload with fields to update (e.g. name, description, logo, modules, buyers). Returns the updated user group object.
User group identifier.
OK
Bad Request
Not Found
PUT /public/v1/accounts/user-groups/{id} HTTP/1.1
Host: api.platform.softwareone.com
Content-Type: application/json
Accept: */*
Content-Length: 101
{
"name": "Rolls-Royce Updated",
"description": "Updated description",
"modules": [
{
"id": "MOD-1756-1452"
}
]
}{
"id": "UGR-5116-6265",
"revision": 2,
"name": "Rolls-Royce Updated",
"description": "Updated description",
"isDefault": false,
"account": {
"id": "ACC-1234-5678",
"name": "Microsoft"
},
"modules": [
{
"id": "MOD-1756-1452"
}
],
"audit": {
"created": {
"at": "2024-02-01T09:12:23+00:00",
"by": {
"id": "USR-0001",
"name": "Ops User"
}
},
"updated": {
"at": "2024-02-02T10:00:00+00:00",
"by": {
"id": "USR-0001",
"name": "Ops User"
}
}
}
}Get user group by ID. Returns a single user group with id, name, description, account, modules, users, buyers, and default flag. Optional select query parameter controls which fields are returned.
User group identifier.
Optional RQL select statement to limit returned fields.
OK
Not Found
GET /public/v1/accounts/user-groups/{id} HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
{
"id": "UGR-5116-6265",
"revision": 2,
"name": "Test-1",
"description": "Group for access management",
"isDefault": false,
"account": {
"id": "ACC-1234-5678",
"name": "Microsoft"
},
"modules": [
{
"id": "MOD-1756-1452",
"name": "Access management"
},
{
"id": "MOD-9042-8216",
"name": "Account management"
}
],
"users": [
{
"id": "USR-0000-0016",
"name": "Astha Pruthi"
}
]
}List user groups. Returns a paged list of user groups; supports RQL query parameters for filtering and selection.
OK
GET /public/v1/accounts/user-groups HTTP/1.1
Host: api.platform.softwareone.com
Accept: */*
OK
{
"data": [
{
"id": "UGR-5116-6265",
"revision": 2,
"name": "Test-1",
"description": "Group for access management",
"isDefault": false,
"account": {
"id": "ACC-1234-5678",
"name": "Microsoft"
},
"modules": [
{
"id": "MOD-1756-1452"
},
{
"id": "MOD-9042-8216"
}
]
}
],
"$meta": {
"pagination": {
"offset": 0,
"limit": 10,
"total": 1
}
}
}Create user group. Accepts account reference, name, optional description and logo, modules (at least one), and optional buyers and extensions. Returns the created user group object with revision 1.
^ACC-\d\d\d\d-\d\d\d\d$^ACC-\d\d\d\d-\d\d\d\d$^ACC-\d\d\d\d-\d\d\d\d$^ACC-\d\d\d\d-\d\d\d\d$^ACC-\d\d\d\d-\d\d\d\d$^MOD-\d\d\d\d$^MOD-\d\d\d\d$^BUY-\d\d\d\d-\d\d\d\d$Created
Bad Request
POST /public/v1/accounts/user-groups HTTP/1.1
Host: api.platform.softwareone.com
Content-Type: application/json
Accept: */*
Content-Length: 188
{
"account": {
"id": "ACC-1234-5678"
},
"name": "Rolls-Royce",
"description": "The best car producer ever",
"modules": [
{
"id": "MOD-1756-1452"
},
{
"id": "MOD-9042-8216"
}
],
"buyers": null,
"extensions": null
}{
"id": "UGR-5116-6265",
"revision": 1,
"name": "Rolls-Royce",
"description": "The best car producer ever",
"isDefault": false,
"account": {
"id": "ACC-1234-5678",
"name": "Microsoft"
},
"modules": [
{
"id": "MOD-1756-1452"
},
{
"id": "MOD-9042-8216"
}
],
"audit": {
"created": {
"at": "2024-02-01T09:12:23+00:00",
"by": {
"id": "USR-0001",
"name": "Ops User"
}
},
"updated": {
"at": "2024-02-01T09:12:23+00:00",
"by": {
"id": "USR-0001",
"name": "Ops User"
}
}
}
}