Resource: User Groups ( /api/user/{id}/groups )
Collection resource of groups a user belongs to.
This resource supports the following methods: GET, PUT
Methods
GET
Retrieves all (or a subset) of groups a user belongs to.
This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.
Supported Expansions
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
| Status | Description |
|---|---|
| 200 - OK | Returned if the request was completed successfully. |
An example of fetching all groups.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Parameters
| Key | Value | Description |
|---|---|---|
| {id} | 8E064E7A-847F-4853-AFFF-2CD1803664D7 | The ID of the user to fetch group membership for |
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 |
Response Body
[
{
"Id": "4109a8f4-58cc-4c91-a1db-ef01b0ccbd44",
"Name": "Admins",
"Description": "System Administrators",
"Self": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44",
"Links": [
{
"Title": "Members",
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/users",
"Rel": "Users"
},
{
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/permissions/projects",
"Rel": "ProjectPermissions"
}
]
},
{
"Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Name": "QA",
"Description": "QA Team (Testers + Test Managers)",
"Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Links": [
{
"Title": "Members",
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
"Rel": "Users"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
"Rel": "ProjectPermissions"
}
]
}
]
Status Code
200 - OK
An example of fetching a set of groups filtered by name, by using the ODATA $filter query parameter.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Parameters
| Key | Value | Description |
|---|---|---|
| {id} | 8E064E7A-847F-4853-AFFF-2CD1803664D7 | The ID of the user to fetch group membership for |
| $filter | Name eq 'QA' | The ODATA $filter parameter, this query parameter should be url encoded i.e. $filter=Name%20eq%20'QA' . |
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 |
Response Body
[
{
"Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Name": "QA",
"Description": "QA Team (Testers + Test Managers)",
"Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Links": [
{
"Title": "Members",
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
"Rel": "Users"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
"Rel": "ProjectPermissions"
}
]
}
]
Status Code
200 - OK
PUT
Sets the groups the user is a member of.
This method supports the OData parameters $filter, $top, $take, $orderby and $inlinecount. See OData Topic for more details.
Required Permissions
- Administration/Organisation/ManageUserAndGroupSecurity
Supported Expansions
For more details on expansions, please see the Expand help topic.
Status Codes
These are the expected status codes returned by the service. In addition, some other status codes may be returned if either an internal error occurs or there is an authentication issue (such as an expired OAuth token).
| Status | Description |
|---|---|
| 200 - OK | Returned if the request was completed successfully. |
| 404 - NotFound | Returned if user does not exist. |
Set the groups a user belongs to.
Request Headers
| Key | Value | Description |
|---|---|---|
| Accept | application/json |
Request Parameters
| Key | Value | Description |
|---|---|---|
| {id} | 8E064E7A-847F-4853-AFFF-2CD1803664D7 | The ID of the user to set groups for. |
Request Body
{
"Items": [
{
"Id": "4109a8f4-58cc-4c91-a1db-ef01b0ccbd44"
},
{
"Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d"
}
]
}
Response Headers
| Key | Value | Description |
|---|---|---|
| Content-Type | application/json; charset=utf-8 |
Response Body
[
{
"Id": "4109a8f4-58cc-4c91-a1db-ef01b0ccbd44",
"Name": "Admins",
"Description": "System Administrators",
"Self": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44",
"Links": [
{
"Title": "Members",
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/users",
"Rel": "Users"
},
{
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Href": "http://localhost/api/group/4109a8f4-58cc-4c91-a1db-ef01b0ccbd44/permissions/projects",
"Rel": "ProjectPermissions"
}
]
},
{
"Id": "9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Name": "QA",
"Description": "QA Team (Testers + Test Managers)",
"Self": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d",
"Links": [
{
"Title": "Members",
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/users",
"Rel": "Users"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/global",
"Rel": "GlobalPermissions"
},
{
"Href": "http://localhost/api/group/9e1ee34b-f96f-4005-9f7a-1457df86256d/permissions/projects",
"Rel": "ProjectPermissions"
}
]
}
]
Status Code
200 - OK