Create a Group

Edit on GitHubEdit MD

This API is used to create a new Group.

Request#

Create a Group with a randomly generated Id

POST/api/group

OpenAPI Spec

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

When only a single tenant is configured the tenant Id can be assumed and this additional header is optional. Once more than one tenant has been configured in FusionAuth the tenant Id is required for this request. 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.

Create a Group with the provided unique Id

POST/api/group/{groupId}

OpenAPI Spec

Request Parameters#

groupId UUID optional Defaults to secure random UUID Immutable

The Id to use for the new Group. If not specified a secure random UUID will be generated.

Request Headers#

X-FusionAuth-TenantId String optional

The unique Id of the tenant used to scope this API request.

See Making an API request using a Tenant Id for additional information.

Request Body#

group.data Object optional

An object that can hold any information about the Group that should be persisted.

group.name String required

The name of the Group.

roleIds Array<UUID> optional

The Application Roles to assign to this group.

Example Request JSON

{
  "group": {
    "data": {
      "description": "This group assigns members admin access to all applications.",
      "external": {
        "createdAt": 1503000771468
      }
    },
    "name": "Company Admins"
  },
  "roleIds": [
    "68259c40-0b4e-4245-8956-7e5af0959c2b",
    "00f24e72-52e2-4f55-8ea1-6a06bfe10df5",
    "11a5b1b8-7ef5-476f-af7d-69e19796fa8b"
  ]
}

Response#

The response for this API contains the Group that was created.

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#

group.data Object

An object that can hold any information about the Group that should be persisted.

group.id UUID

The unique Id of the Group.

group.insertInstant Long

The instant that the Group was added to the FusionAuth database.

group.lastUpdateInstant Long

The instant that the Group was updated in the FusionAuth database.

group.name String

The name of the Group.

group.roles Map<UUID, List<Object>

The roles assigned to this Group. The map key is the Application Id, the value is an array of Application Roles.

group.roles[applicationId][x].description String

The description of the role.

group.roles[applicationId][x].id UUID

The Application Role Unique Id

group.roles[applicationId][x].name String

The name of the Group.

group.roles[applicationId][x].isDefault Boolean

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.

group.roles[applicationId][x].isSuperRole Boolean

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.

group.tenantId UUID

The unique Id of the Tenant.

Example Response JSON

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