Public REST API

1 Public Endpoints
- 1.1 Generating and managing Personal Access tokens
- 1.2 Create Space Group
  - 1.2.1 Params
  - 1.2.2 Response
- 1.3 Delete Space Group
  - 1.3.1 Params
  - 1.3.2 Response
- 1.4 Add Group Members
  - 1.4.1 Params
  - 1.4.2 Response
- 1.5 Remove Group Members
  - 1.5.1 Params
  - 1.5.2 Response
- 1.6 Add Delegated Group Members
  - 1.6.1 Params
  - 1.6.2 Response
- 1.7 Remove Delegated Group Members
  - 1.7.1 Params
  - 1.7.2 Response
- 1.8 Retrieve Audit Entries
  - 1.8.1 Params
  - 1.8.2 Response
- 1.9 Export Group Members From 5.0.3
  - 1.9.1 Params
  - 1.9.2 Response
  - 1.9.3 Best case time performance
  - 1.9.4 Authorization
2 Public Component Classes
- 2.1 IPublicCSUMSpaceGroupManager
- 2.2 IPublicCSUMDlgSpaceGroupManager

Since v3.1.4, CSUM provides the option to hook into Public API REST Resources and Components, allowing 3rd party Developers to externally perform CSUM operations outside of the app.

Public Endpoints

You will need to perform these requests as the logged in user that has authorisation to the specific operation.

For example, using a curl command will require authorization using wither:

Basic authentication, i.e -u username:password to authenticate.
Personal Access token authentication, i.e "Authorization: Bearer NzY5OTIzMDU3MzY4OqBxehBgO5emkPDavs8/tri242J/" to authenticate

Generating and managing Personal Access tokens

Manage API tokens for your Atlassian account | Atlassian Support
Using Personal Access Tokens | Atlassian Support | Atlassian Documentation

Create Space Group

Allows the creation of a new Space Group using the provided groupName with the provided spaceKey.

Endpoint

Endpoint
`/rest/csum/latest/public/group/create?spaceKey=<spaceKey>&groupName=<groupName>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space the group should be created in and given the SpaceGroupPattern prefix/suffix from.
`groupName`	The name of the new Group to be created. This should contain the spaceKey suffix/prefix

SpaceGroupPattern is applied on this operation, for example:

#Example curl request using basic auth on a confluence debug instance

curl -u admin:admin -X POST -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/create?spaceKey=TESTSPACE&groupName=new-group

#Example curl request using Personal Access token auth on a confluence debug instance

curl -X POST -H 'Content-Type: application/json' "Authorization: Bearer NzY5OTIzMDUZMYY4OqBxChBgO5emkPDavs8/tri242J/" "http://localhost:1990/confluence/rest/csum/latest/public/group/create?spaceKey=TESTSPACE&groupName=new-group"

# This creates a new group "testspace-new-group" if the SpaceGroupPattern prefix is set.

Response

Returns the status code of the request if authentication is valid, else a 401 response page from Atlassian will be returned (which is not an int).

Response Type: int	Status Type	Description

Response Type: int	Status Type	Description
200	OK	Group Created successfully.
400	Bad Request	This can occur due to invalid Licensing or invalid SpaceKey provided.
409	Conflict	This can occur if a group creation attempts to create a group with the same name as an existing space group.

Delete Space Group

Allows the deletion of an existing Space Group using the provided groupName with the provided spaceKey.

Endpoint

Endpoint
`/rest/csum/latest/public/group/delete?spaceKey=<spaceKey>&groupName=<groupName>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space the group should be deleted from.
`groupName`	The name of the Group to be deleted. This should contain the spaceKey suffix/prefix

SpaceGroupPattern is applied on this operation, for example:

#Example curl request using basic auth on a confluence debug instance

curl -u admin:admin -X DELETE -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/delete?spaceKey=TESTSPACE&groupName=new-group

#Example curl request using Personal Access token auth on a confluence debug instance

curl -X DELETE -H 'Content-Type: application/json' "Authorization: Bearer NzY5OTIzMDUZMYY4OqBxChBgO5emkPDavs8/tri242J/" "http://localhost:1990/confluence/rest/csum/latest/public/group/delete?spaceKey=TESTSPACE&groupName=new-group"

# This deletes the group "testspace-new-group" if the SpaceGroupPattern prefix is set.

Response

Returns the status code of the request if authentication is valid, else a 401 response page from Atlassian will be returned (which is not an int).

Response Type: int	Status Type	Description

Response Type: int	Status Type	Description
200	OK	Group Deleted successfully.
400	Bad Request	This can occur due to invalid Licensing or invalid SpaceKey provided.
409	Conflict	This can occur if a group creation attempts to create a group with the same name as an existing space group.

Add Group Members

Allows the addition of Users and Group Members to the provided SpaceGroups.

Endpoint

Endpoint
`/rest/csum/latest/public/group/addusers?spaceKey=<spaceKey>&spaceGroups=<spaceGroups>&spaceUsers=<spaceUsers>&importViaGroups=<importViaGroups>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space to operate against.
`spaceGroups`	CSV Split values of the SpaceGroup names you want to add members to
`spaceUsers`	CSV split usernames of users you want to add to the groups found in `spaceGroups`
`importViaGroups`	CSV split GroupNames of Groups. All members in these groups will be added into the groups from `spaceGroups` if valid.

#Example curl request using basic auth on a debug confluence instance

curl -u admin:admin -X PUT -H 'Content-Type: application/json' "http://localhost:1990/confluence/rest/csum/latest/public/group/addusers?spaceKey=TEST&spaceGroups=test-newgroupname&spaceUsers=admin

#Example curl request using Personal Access token auth on a confluence debug instance

curl -X PUT -H 'Content-Type: application/json' "Authorization: Bearer NzY5OTIzMDUZMYY4OqBxChBgO5emkPDavs8/tri242J/" "http://localhost:1990/confluence/rest/csum/latest/public/group/addusers?spaceKey=TEST&spaceGroups=test-newgroupname&spaceUsers=admin"

# This adds the user "admin" into the group "test-newgroupname" if valid.

Response

Returns the Response of failed users. If all is successful, {} should be returned.

Response:	Status Type	Description

Response:	Status Type	Description
`{}`	OK	Members added to group without error.
`{"admindd":"invalid"}`	All invalid users	If the user value is invalid/user could not be found, they will return with an ‘invalid’ value.
`{"admin":"membership"}`	All users with membership	If a user is attempted to be added to the provided groups but already has membership, they will return with a ‘membership’ value.

Remove Group Members

Allows the removal of Users and Group Members to the provided SpaceGroups.

Endpoint

Endpoint
`/rest/csum/latest/public/group/removeusers?spaceKey=<spaceKey>&spaceGroups=<spaceGroups>&spaceUsers=<spaceUsers>&importViaGroups=<importViaGroups>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space to operate against.
`spaceGroups`	CSV Split values of the SpaceGroup names you want to remove members from.
`spaceUsers`	CSV split usernames of users you want to remove from the groups found in `spaceGroups`
`importViaGroups`	CSV split GroupNames of Groups. All members in these groups will be removed from the groups from `spaceGroups` if valid.

Response

Returns the Response of the operation. If all is successful, no value is returned.

Response:	Status Type	Description

Response:	Status Type	Description
<No Value>	OK	Members removed from group without error.
`<Value>`	Invalid SpaceKey	If the SpaceKey value provided is returned, it is not a valid SpaceKey.
`NullPointerException`	Invalid / No Groups Provided	If `spaceGroups` contains no valid Groups, Group Membership removal can not occur.

Add Delegated Group Members

Allows the addition of Users and Group Members to the provided Delegated Groups.

Endpoint

Endpoint
`/rest/csum/latest/public/dlggroup/addusers?spaceKey=<spaceKey>&dlgGroups=<dlgGroups>&spaceUsers=<spaceUsers>&importViaGroups=<importViaGroups>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space to operate against.
`dlgGroups`	CSV Split values of the Delegated Group names you want to add members to
`spaceUsers`	CSV split usernames of users you want to add to the groups found in `dlgGroups`
`importViaGroups`	CSV split GroupNames of Groups. All members in these groups will be added into the groups from `dlgGroups` if valid.

Response

Returns JSONAddUserResultBean[]. Example Response and Bean values are listed below.

Response:	Status Type	Description

Response:	Status Type	Description
`[{"groupName":"test-group","successCount":1,"totalUsers":1,"failedUsers":[],"failedUserNames":[],"failedUserReasons":[]}]`	Example Bean Response	Bean response for each ‘add’ operation on `dlgGroups`

Remove Delegated Group Members

Allows the removal of Users and Group Members to the provided Delegated Groups.

Endpoint

Endpoint
`/rest/csum/latest/public/dlggroup/removeusers?spaceKey=<spaceKey>&dlgGroups=<dlgGroups>&spaceUsers=<spaceUsers>&importViaGroups=<importViaGroups>`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	The SpaceKey of the Space to operate against.
`dlgGroups`	CSV Split values of the SpaceGroup names you want to remove members from.
`spaceUsers`	CSV split usernames of users you want to remove from the groups found in `spaceGroups`
`importViaGroups`	CSV split GroupNames of Groups. All members in these groups will be removed from the groups from `spaceGroups` if valid.

Response

Returns the Response of the operation. If all is successful, [] (Empty Array) is returned.

Response:	Status Type	Description

Response:	Status Type	Description
`[]`	OK	Members removed from group without error.
`[<Value>]`	Invalid Users provided	If `spaceUsers` or `importViaGroups` have users that were not members of `dlgGroups`, they will be returned here.

Retrieve Audit Entries

Allows the retrieval of Audit Entries with pagination and offset limits.

Endpoint

Endpoint
`/rest/csum/latest/public/group/removeusers?spaceKey=<spaceKey>&spaceGroups=<spaceGroups>&spaceUsers=<spaceUsers>&importViaGroups=<importViaGroups>`

Params

QueryParam Name	Description

QueryParam Name	Description
`draw`	The draw counter for calling audit event retrieval. The most recent (largest value) draw is returned
`start`	The entry ID start point
`length`	The total number of audit entries to retrieve (E.g. length=10 will return max 10 results)
`orderCol`	The column to be ordered against matching the In-App table (int)
`orderDirStr`	The direction of audit entries ("asc"/"desc")
`outcomeVal`	success / error / unauthorized
`groupVal`	The Context Group that was Operated on
`userVal`	The Context User that was Operated on
`spaceKey`	The space to retrieve audit entries for

Response

Returns the JSON response of the Audit entries found matching the given criteria.

Export Group Members From 5.0.3

Provides an export of Group Members from a Group within Confluence.

Endpoint

Endpoint
`/rest/csum/latest/public/group/members?spaceKey=test&groupName=test-hi"`

Params

QueryParam Name	Description

QueryParam Name	Description
`spaceKey`	A SpaceKey that the user perfoming this operation is an administrator of.
`groupName`	The name of the Group which will have its members exported

Response

Returns the JSON response of the Group members found.

Best case time performance

This will be dependent on the machine performing this request as well as any mitigating other factors

Group membership count	Time duration to complete export

Group membership count	Time duration to complete export
10	< 1 Second
50	< 1 Second
100	< 1 Second
250	< 1 Second
1000	< 1 Second
5000	< 30 Seconds
10000	< 2 Minutes
25000	< 15 Minutes
50000	< 1 Hour
100000	< 4 Hours

Authorization

In order to be able to perform the Group members export, the User performing the request must be authorized through CSUM:

The user must be a Space Admin of the Space referred by the spaceKey query parameter
The referred groupName Group is either:
1. A valid Space Group matching the Space Group Pattern for the space, see Admin : Space Group Config
2. A valid Delegated Group to that specific user, see Delegated Groups

Public Component Classes

The following Interfaces are exposed to perform the same functionality as above. These Classes can be used internally within your code to hook into CSUM’s operations.

IPublicCSUMSpaceGroupManager

Method Name	Description	Returns

Method Name	Description	Returns
`createSpaceGroup(Space space, String groupName)`	Allows SpaceGroup creation	`Group` The Group created.
`deleteSpaceGroup(Space space, String groupName)`	Allows SpaceGroup deletion	`boolean` Boolean value of if Group was deleted successfully or not.
`addUsersToGroups(Space space, String spaceGroups, String spaceUsers, String importViaGroups)`	Allows Group Membership addition	`Pair<List<String>, List<String>>` Left List returns failed Users, Right List returns invalid Groups.
`removeGroupMembers(Space space, @Nonnull String spaceGroupCsv, String userNameCsv, String membershipGroupsCsv)`	Allows Group Membership removal	`void` - no return value.

Example:

IPublicCSUMDlgSpaceGroupManager

Method Name	Description	Returns

Method Name

Description

Returns

addUsersToGroups(Space space, String groupNames, String userNames, String importViaGroups)

Allows Group Membership addition for Authorized Delegated Space Groups

JSONAddUserResultBean[]

Response Bean of operation info (Success total, failed users, etc)

removeUsersSpaceDlgGroups(String dlgGroups, String userNames, String membershipGroups, String spaceKey)

Allows Group Membership removal for Authorized Delegated Space Groups

List<String>

List of failed users

Example: