Search for Groups API
On this page
1.45.0
This API is used to search for Groups and may be called using the GET or POST HTTP methods. Examples of each are provided below. The POST method is provided to allow for a richer request object without worrying about exceeding the maximum length of a URL. Calling this API with either the GET or POST HTTP method will provide the same search results given the same query parameters.
Request#
Use a POST request to instead send the search criteria in a JSON request body.
OpenAPI Spec
Request Headers#
X-FusionAuth-TenantIdThe unique Id of the tenant used to scope this API request.
The tenant Id is not required on this request even when more than one tenant has been configured because the tenant can be identified based upon other values in the request or it is otherwise not required.
Specify a tenant Id on this request when you want to ensure the request is scoped to a specific tenant. The tenant Id may be provided through this header or by using a tenant locked API key to achieve the same result.
See Making an API request using a Tenant Id for additional information.
Query Parameters#
nameThe case-insensitive string to search for in the Group name. This can contain wildcards using the asterisk character (*). If no wildcards are present, the search criteria will be interpreted as *value*.
numberOfResultsThe number of results to return from the search.
orderByThe database field to order the search results as well as an order direction.
The possible values are:
id- the unique Id of the GroupinsertInstant- the instant when the Group was createdname- the Group nametenant- the name of the Tenant in which the Group belongs
The order direction is optional. Possible values of the order direction are ASC or DESC. If omitted, the default sort order is ASC.
For example, to order the results by the insert instant in a descending order, use insertInstant DESC.
startRowThe offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
For example, if the total search results are greater than the page size designated by numberOfResults, set this value to 25 to retrieve results 26-50, assuming the default page size.
tenantIdRestricts the results to Groups belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.
Request Body#
search.name The case-insensitive string to search for in the Group name. This can contain wildcards using the asterisk character (*). If no wildcards are present, the search criteria will be interpreted as *value*.
search.numberOfResults The number of results to return from the search.
search.orderBy The database field to order the search results as well as an order direction.
The possible values are:
id- the unique Id of the GroupinsertInstant- the instant when the Group was createdname- the Group nametenant- the name of the Tenant in which the Group belongs
The order direction is optional. Possible values of the order direction are ASC or DESC. If omitted, the default sort order is ASC.
For example, to order the results by the insert instant in a descending order, use insertInstant DESC.
search.startRow The offset into the total results. In order to paginate the results, increment this value by the numberOfResults for subsequent requests.
For example, if the total search results are greater than the page size designated by numberOfResults, set this value to 25 to retrieve results 26-50, assuming the default page size.
search.tenantId Restricts the results to Groups belonging to the given Tenant. This parameter will be overridden if the request contains an X-FusionAuth-TenantId header, or if the supplied API key is scoped to a specific Tenant.
{
"search": {
"name": "Admins",
"tenantId": "50435e55-6e95-4d54-96d0-9c953dd53eeb",
"numberOfResults": 25,
"orderBy": "insertInstant",
"startRow": 0
}
}Response#
The response for this API contains the Groups matching the search criteria in paginated format.
Response Codes| Code | Description |
|---|---|
| 200 | The request was successful. The response will contain a JSON body. |
| 400 | The request was invalid and/or malformed. The response will contain an Errors JSON Object with the specific errors. This status will also be returned if a paid FusionAuth license is required and is not present. |
| 401 | You did not supply a valid Authorization header. The header was omitted or your API key was not valid. The response will be empty. See Authentication. |
| 500 | There was an internal error. A stack trace is provided and logged in the FusionAuth log files. The response will be empty. |
Response Body#
Response Body#
groupsThe list of Group objects.
groups[x].data An object that can hold any information about the Group that should be persisted.
groups[x].id The name of the Group.
group[x].insertInstant The instant that the Group was added to the FusionAuth database.
group[x].lastUpdateInstant The instant that the Group was updated in the FusionAuth database.
groups[x].name The name of the Group.
groups[x].roles The roles assigned to this Group. The map key is the Application Id, the value is an array of Application Roles.
groups[x].roles[applicationId][x].description The description of the role.
groups[x].roles[applicationId][x].id The Application Role Unique Id
groups[x].roles[applicationId][x].name The name of the Group.
groups[x].roles[applicationId][x].isDefault Whether or not the Role is a default role. A default role is automatically assigned to a user during registration if no roles are provided.
groups[x].roles[applicationId][x].isSuperRole Whether or not the Role is a considered to be a super user role. This is a marker to indicate that it supersedes all other roles. FusionAuth will attempt to enforce this contract when using the web UI, it is not enforced programmatically when using the API.
groups[x].tenantId The unique Id of the Tenant.
totalThe total number of Groups matching the search criteria. Use this value along with the numberOfResults and startRow in the Search request to perform pagination.
{
"groups": [
{
"data": {
"description": "This group assigns members admin access to all applications.",
"external": {
"createdAt": 1503000771468
}
},
"id": "1188edfc-cef3-4555-910e-181ddf6153c0",
"insertInstant": 1595361142909,
"lastUpdateInstant": 1595361143101,
"name": "Company Admins",
"roles": {
"931fded0-f917-439d-b447-d7f21b37a134": [
{
"id": "68259c40-0b4e-4245-8956-7e5af0959c2b",
"isDefault": false,
"isSuperRole": true,
"name": "admin"
}
],
"07d1efe7-9a14-433d-8247-2235e67736f0": [
{
"id": "00f24e72-52e2-4f55-8ea1-6a06bfe10df5",
"isDefault": false,
"isSuperRole": true,
"name": "ADMIN"
}
],
"d23e9a51-2b20-4384-9c74-432e12219aad": [
{
"id": "11a5b1b8-7ef5-476f-af7d-69e19796fa8b",
"isDefault": false,
"isSuperRole": true,
"name": "Administrator"
}
]
},
"tenantId": "30663132-6464-6665-3032-326466613934"
}
],
"total": 1
}Related
API documentation for the FusionAuth Add Users to a Group API.
API documentation for the FusionAuth Create a Group API.
API documentation for the FusionAuth Delete a Group API.
Learn about the APIs for creating, retrieving, updating and deleting groups.