Group Management API

Custom Groups

List Groups

This endpoint returns a list of all custom groups.

URI Request Type

PROPFIND

remote.php/dav/customgroups/groups/

curl --silent \
  -X PROPFIND \
  --data "@list-custom-groups.xml" \
  -u username:password \
  'http://localhost/remote.php/dav/customgroups/groups/' \
  | xmllint --format -
....

.list-custom-groups.xml
[source,xml]
....
<?xml version="1.0" encoding="UTF-8"?>
<oc:customgroups
    xmlns:a="DAV:"
    xmlns:oc="http://owncloud.org/ns">
    <a:prop>
        <a:getlastmodified />
        <a:getcontentlength/>
        <a:quota-used-bytes/>
        <a:quota-available-bytes/>
        <a:getetag/>
        <a:getcontenttype/>
    </a:prop>
</oc:customgroups>
....

Successful requests return two things:

. An XML payload.
. A status of `HTTP/1.1 207 Multi-Status`.

You can see an example of the XML payload below.
The XML payload contains a `response` element for each group.

[source,xml]
....
<?xml version="1.0"?>
<d:multistatus
    xmlns:d="DAV:"
    xmlns:s="http://sabredav.org/ns"
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/customgroups/groups/</d:href>
    <d:propstat>
      <d:prop>
        <d:resourcetype>
          <d:collection/>
          <oc:customgroups-groups/>
        </d:resourcetype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
  <d:response>
    <d:href>/remote.php/dav/customgroups/groups/testgroup/</d:href>
    <d:propstat>
      <d:prop>
        <d:resourcetype>
          <d:collection/>
          <oc:customgroups-group/>
        </d:resourcetype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
    <d:propstat>
      <d:prop>
        <d:getlastmodified/>
        <d:getcontentlength/>
        <d:quota-used-bytes/>
        <d:quota-available-bytes/>
        <d:getetag/>
        <d:getcontenttype/>
      </d:prop>
      <d:status>HTTP/1.1 404 Not Found</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>
....

==== No Results

If there are no custom groups, then a response similar to the following will be returned.

[source,xml]
....
<?xml version="1.0"?>
<d:multistatus
    xmlns:d="DAV:"
    xmlns:s="http://sabredav.org/ns"
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/customgroups/groups/</d:href>
    <d:propstat>
      <d:prop>
        <d:resourcetype>
          <d:collection/>
          <oc:customgroups-groups/>
        </d:resourcetype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>

....

=== Rename Custom Group
:request_method: PROPPATCH
:request_data_file: rename-custom-group.xml
:request_path_suffix: <$groupId>

This endpoint allows a custom group to be renamed.

NOTE: Only group admins can rename the groups that they manage.

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`PROPFIND`
|`remote.php/dav/customgroups/groups/`
|===


[source,console,subs="attributes+"]

curl --silent \ -X PROPFIND \ --data "@list-custom-groups.xml" \ -u username:password \ 'http://localhost/remote.php/dav/customgroups/groups/' \ | xmllint --format -

.{request_data_file}
[source,xml]

<?xml version="1.0" encoding="UTF-8"?> <a:propertyupdate xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns"> <a:prop> <oc:display-name>test_group</oc:display-name> </a:prop> </a:propertyupdate>

==== Responses

===== Success

A successful request will only return a status of `HTTP/1.1 204 No Content`.
No other information will be returned or displayed.

===== Failure

====== Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of `HTTP/1.1 401 Unauthorized` will be returned.

If the user making the request has insufficient privileges to make the request then a status of `HTTP/1.1 401 Unauthorized` will be returned, along with the following XML in the response’s body:

[source,xml]

<?xml version="1.0" encoding="utf-8"?> <d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"> <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception> <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message> </d:error>

====== Missing Group

If the specified group does not exist, then the following XML response body will be returned, along with an `HTTP/1.1 207 Multi-Status` status.

[source,xml]

<?xml version="1.0" encoding="utf-8"?> <d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"> <s:exception>Sabre\DAV\Exception\NotFound</s:exception> <s:message>Group with uri "testgroup" not found</s:message> </d:error>

===  Delete Group
:request_method: DELETE
:request_data_file:
:request_path_suffix: <$groupId>

This endpoint allows for a custom group to be deleted.

NOTE: Only group admins can delete a group.

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`{request_method}`
|`{request_base_path}/{request_path_suffix}`
|===


[source,console,subs="attributes+"]
----
curl --silent \
  -X {request_method} \
  --data "@{request_data_file}" \
  -u {oc-examples-username}:{oc-examples-password} \
  'http://localhost/{request_base_path}/{request_path_suffix}' \
  | xmllint --format -

Responses

Success

A successful request will only return a status of HTTP/1.1 204 No Content. No other information will be returned or displayed.

Failure
Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of HTTP/1.1 401 Unauthorized will be returned.

If the user making the request has insufficient privileges to make the request then a status of HTTP/1.1 401 Unauthorized will be returned, along with the following XML in the response’s body:

<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception>
  <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message>
</d:error>

Create Group

This endpoint allows for creating a custom group.

The group’s creator automatically becomes the group’s admin and its initial member.
URI Request Type

MKCOL

remote.php/dav/customgroups/groups/<$groupId>

curl --silent \
  -X MKCOL \
  --data "@list-custom-groups.xml" \
  -u username:password \
  'http://localhost/remote.php/dav/customgroups/groups/&lt;$groupId&gt;' \
  | xmllint --format -
....

==== Responses

===== Success

A successful request will only return a status of `HTTP/1.1 201 Created`.
No other information will be returned or displayed.

===== Failure

====== Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of `HTTP/1.1 401 Unauthorized` will be returned.

If the user making the request has insufficient privileges to make the request then a status of `HTTP/1.1 401 Unauthorized` will be returned, along with the following XML in the response’s body:

[source,xml]
....
<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception>
  <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message>
</d:error>
....


== Group Membership
:page-partial:
:request_base_path: /remote.php/dav/customgroups/users

// this page is included via groups.adoc
// some variables like request_base_path used in includes here are defined there

===  List Members
:request_method: PROPFIND
:request_data_file: list-custom-group-members.xml
:request_path_suffix:

This endpoint allows for listing all of the members in a custom group.

NOTE: Only group members can list a group's members. Other users will receive a status of `HTTP/1.1 403 Forbidden`

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`MKCOL`
|`remote.php/dav/customgroups/groups/&lt;$groupId&gt;`
|===


[source,console,subs="attributes+"]

curl --silent \ -X MKCOL \ --data "@list-custom-groups.xml" \ -u username:password \ 'http://localhost/remote.php/dav/customgroups/groups/<$groupId>' \ | xmllint --format -

.{request_data_file}
[source,xml]

<?xml version="1.0" encoding="UTF-8"?> <a:propfind xmlns:a="DAV:" xmlns:oc="http://owncloud.org/ns"> <a:prop> <oc:role/> </a:prop> </a:propfind>

==== Responses

===== Success

Successful requests return two things:

. An XML payload.
. A status of `HTTP/1.1 207 Multi-Status`.

You can see an example of the XML payload below.

[source,xml]

<?xml version="1.0"?> <d:multistatus xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns" xmlns:oc="http://owncloud.org/ns"> <d:response> <d:href>/remote.php/dav/customgroups/groups/testgroup2/</d:href> <d:propstat> <d:prop> <oc:role/> </d:prop> <d:status>HTTP/1.1 404 Not Found</d:status> </d:propstat> </d:response> <d:response> <d:href>/remote.php/dav/customgroups/groups/testgroup2/admin</d:href> <d:propstat> <d:prop> <oc:role>admin</oc:role> </d:prop> <d:status>HTTP/1.1 200 OK</d:status> </d:propstat> </d:response> </d:multistatus>

===== Failure

====== Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of `HTTP/1.1 401 Unauthorized` will be returned.

If the user making the request has insufficient privileges to make the request then a status of `HTTP/1.1 401 Unauthorized` will be returned, along with the following XML in the response’s body:

[source,xml]

<?xml version="1.0" encoding="utf-8"?> <d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"> <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception> <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message> </d:error>

===  Add Member
:request_method: PUT
:request_data_file:
:request_path_suffix: <$numericGroupId>/<$userId>

This endpoint allows for adding members to a custom group.

NOTE: Only group admins can add members.

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`{request_method}`
|`{request_base_path}/{request_path_suffix}`
|===


[source,console,subs="attributes+"]
----
curl --silent \
  -X {request_method} \
  --data "@{request_data_file}" \
  -u {oc-examples-username}:{oc-examples-password} \
  'http://localhost/{request_base_path}/{request_path_suffix}' \
  | xmllint --format -

Responses

Success

If the request succeeds, then only a HTTP/1.1 201 Created status will be returned.

Failure
Method Not Allowed

If the request was made using any other method than PUT, then an HTTP/1.1 405 Method Not Allowed status will be returned, along with the XML payload below:

<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\MethodNotAllowed</s:exception>
  <s:message>Cannot create collections</s:message>
</d:error>
Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of HTTP/1.1 401 Unauthorized will be returned.

If the user making the request has insufficient privileges to make the request then a status of HTTP/1.1 401 Unauthorized will be returned, along with the following XML in the response’s body:

<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception>
  <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message>
</d:error>

Remove Member

This endpoint allows for removing members from a custom group.

Only group admins can remove members. Group admins cannot remove themselves if no other admin exists in the group. A group member can remove themselves using this API call.
URI Request Type

DELETE

remote.php/dav/customgroups/groups/<$numericGroupId>/<$userId>

curl --silent \
  -X DELETE \
  --data "@" \
  -u username:password \
  'http://localhost/remote.php/dav/customgroups/groups/&lt;$numericGroupId&gt;/&lt;$userId&gt;' \
  | xmllint --format -
....

==== Responses

===== Success

A successful request will only return a status of `HTTP/1.1 204 No Content`.
No other information will be returned or displayed.

===== Failure

====== Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of `HTTP/1.1 401 Unauthorized` will be returned.

If the user making the request has insufficient privileges to make the request then a status of `HTTP/1.1 401 Unauthorized` will be returned, along with the following XML in the response’s body:

[source,xml]
....
<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception>
  <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message>
</d:error>
....

===  Change Admin Role of a Member
:request_method: PROPPATCH
:request_data_file:
:request_path_suffix: <$numericGroupId>/<$userId>

This endpoint allows for changing the admin role of an existing member of the group.

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`DELETE`
|`remote.php/dav/customgroups/groups/&lt;$numericGroupId&gt;/&lt;$userId&gt;`
|===


[source,console,subs="attributes+"]

curl --silent \ -X DELETE \ --data "@" \ -u username:password \ 'http://localhost/remote.php/dav/customgroups/groups/<$numericGroupId>/<$userId>' \ | xmllint --format -

==== Responses

===== Success

===== Failure

====== Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of `HTTP/1.1 401 Unauthorized` will be returned.

If the user making the request has insufficient privileges to make the request then a status of `HTTP/1.1 401 Unauthorized` will be returned, along with the following XML in the response’s body:

[source,xml]

<?xml version="1.0" encoding="utf-8"?> <d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns"> <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception> <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message> </d:error>

===  List Group Memberships of a Given User
:request_method: PROPFIND
:request_data_file:
:request_base_path: /remote.php/dav/customgroups/users
:request_path_suffix: <$userId>/<$membership>

This endpoint lists the groups that a user is a member of.

[cols="25%,75%",options="header,autowidth"]
|===
|URI
|Request Type

|`{request_method}`
|`{request_base_path}/{request_path_suffix}`
|===


[source,console,subs="attributes+"]
----
curl --silent \
  -X {request_method} \
  --data "@{request_data_file}" \
  -u {oc-examples-username}:{oc-examples-password} \
  'http://localhost/{request_base_path}/{request_path_suffix}' \
  | xmllint --format -

Responses

Success

Successful requests return two things:

  1. An XML payload.

  2. A status of HTTP/1.1 207 Multi-Status.

You can see an example of the XML payload below.

<?xml version="1.0"?>
<d:multistatus
    xmlns:d="DAV:"
    xmlns:s="http://sabredav.org/ns"
    xmlns:oc="http://owncloud.org/ns">
  <d:response>
    <d:href>/remote.php/dav/customgroups/users/settermjd/</d:href>
    <d:propstat>
      <d:prop>
        <d:resourcetype>
          <d:collection/>
          <oc:customgroups-groups/>
        </d:resourcetype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
  </d:response>
  <d:response>
    <d:href>/remote.php/dav/customgroups/users/settermjd/testgroup2/</d:href>
    <d:propstat>
      <d:prop>
        <d:resourcetype>
          <d:collection/>
          <oc:customgroups-group/>
        </d:resourcetype>
      </d:prop>
      <d:status>HTTP/1.1 200 OK</d:status>
    </d:propstat>
    <d:propstat>
      <d:prop>
        <d:getlastmodified/>
        <d:getcontentlength/>
        <d:quota-used-bytes/>
        <d:quota-available-bytes/>
        <d:getetag/>
        <d:getcontenttype/>
      </d:prop>
      <d:status>HTTP/1.1 404 Not Found</d:status>
    </d:propstat>
  </d:response>
</d:multistatus>
Failure
Insufficient Privileges or the User is not Authorized

If the user making the request that only and admin can perform, then a status of HTTP/1.1 401 Unauthorized will be returned.

If the user making the request has insufficient privileges to make the request then a status of HTTP/1.1 401 Unauthorized will be returned, along with the following XML in the response’s body:

<?xml version="1.0" encoding="utf-8"?>
<d:error xmlns:d="DAV:" xmlns:s="http://sabredav.org/ns">
  <s:exception>Sabre\DAV\Exception\NotAuthenticated</s:exception>
  <s:message>No public access to this resource., Username or password was incorrect, Username or password was incorrect</s:message>
</d:error>