Create a Group API

Edit on GitHubView Markdown
On this page

This API is used to create a new Group.

Request#

API Key Authentication
Create a Group with a randomly generated Id
POST/api/group
OpenAPI Spec

Request Headers#

X-FusionAuth-TenantId
  • Type: 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.


API Key Authentication
Create a Group with the provided unique Id
POST/api/group/{groupId}
OpenAPI Spec

Request Parameters#

groupId
  • Type: 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
  • Type: 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.

Request Body#
group.data
  • Type: Object
  • Optional

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

group.name
  • Type: String
  • Required

The name of the Group.

roleIds
  • Type: 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
CodeDescription
200The request was successful. The response will contain a JSON body.
400The 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.
401You 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.
500There 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
  • Type: Object

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

group.id
  • Type: UUID

The unique Id of the Group.

group.insertInstant
  • Type: Long

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

group.lastUpdateInstant
  • Type: Long

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

group.name
  • Type: String

The name of the Group.

group.roles
  • Type: 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
  • Type: String

The description of the role.

group.roles[applicationId][x].id
  • Type: UUID

The Application Role Unique Id

group.roles[applicationId][x].name
  • Type: String

The name of the Group.

group.roles[applicationId][x].isDefault
  • Type: 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
  • Type: 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
  • Type: 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"
  }
}

Related

APIs

Group API

Learn about the APIs for creating, retrieving, updating and deleting groups.

fusionauth apirest apihttp api
APIs

Retrieve a Group API

API documentation for the FusionAuth Retrieve a Group API.

fusionauth apirest apihttp api
APIs

Update a Group API

API documentation for the FusionAuth Update a Group API.

fusionauth apirest apihttp api
APIs

Add Users to a Group API

API documentation for the FusionAuth Add Users to a Group API.

fusionauth apirest apihttp api