Provisioning API
Introduction
The Provisioning API application enables a set of APIs that external systems can use to:
-
Create, edit, delete and query user attributes
-
Query, set and remove groups
-
Set quota and query total storage used in ownCloud
-
Group admin users can also query ownCloud and perform the same functions as an admin for groups they manage.
-
Query for active ownCloud applications, application info, and to enable or disable an app.
HTTP requests can be used via a Basic Auth header to perform any of the functions listed above. The Provisioning API app is enabled by default. The base URL for all calls to the share API is owncloud_base_url/ocs/v1.php/cloud.
Instruction Set For Users
Add User
Create a new user on the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Syntax
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
|
array |
Groups to add the user to (optional). Groups must already exist. |
|
string |
The required password for the new user. |
|
string |
The required username for the new user. |
Status Codes
-
100 - successful
-
101 - invalid input data
-
102 - username already exists
-
103 - unknown error occurred whilst adding the user
-
104 - group does not exist
Usage Examples
curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users \
-d userid="Frank" \
-d password="frankspassword"
curl -X POST http://admin:secret@example.com/ocs/v1.php/cloud/users \
-d userid="Frank" \
-d password="frankspassword" \
-d groups[]="finance" -d groups[]="management"
Get Users
Retrieves a list of users from the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
search |
string |
optional search string |
limit |
int |
optional limit value |
offset |
int |
optional offset value |
Get User
Retrieves information about a single user.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
int |
Id of the user to retrieve |
Get User Example
# Returns information on the user "Frank"
curl http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<status>ok</status>
<statuscode>100</statuscode>
<message/>
</meta>
<data>
<enabled>true</enabled>
<quota>
<free>81919008768</free>
<used>5809166</used>
<total>81924817934</total>
<relative>0.01</relative>
</quota>
<email>user@example.com</email>
<displayname>Frank</displayname>
<home>/mnt/data/files/Frank</home>
<two_factor_auth_enabled>false</two_factor_auth_enabled>
<last_login>1635846303</last_login>
</data>
</ocs>
File Storage Space Quota Response Fields
- free
-
The number of bytes of quota remaining
- used
-
The number of bytes of quota currently used
- total
-
The total number of bytes of storage that the user has permission to use
- relative
-
The percentage of quota currently used
Last Login Response Field
The last_login
response field contains a Unix timestamp number of seconds that represents the date-time that the user last accessed the ownCloud server. Accesses include all requests by the user, such as using the webUI and syncing to/from clients.
If the user has not yet logged in then last_login
is zero.
Edit User
Edits attributes related to a user. Users are able to edit email, displayname and password; admins can also edit the quota value. Exactly one attribute can be set or modified at a time. To set or modify multiple attributes then multiple calls must be made.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
key |
string |
the field to edit (email, quota, display, password) |
value |
mixed |
the new value for the field |
Edit User Example
Updates the email address for the user "Frank"
curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank \
-d key="email" \
-d value="franksnewemail@example.org"
Updates the quota for the user "Frank"
curl -X PUT http://admin:secret@example.com/ocs/v1.php/cloud/users/Frank \
-d key="quota" \
-d value="100MB"
Enable User
Enables a user on the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path |
Method |
Content Type |
|
|
|
Argument |
Type |
Description |
userid |
string |
The id of the user to enable |
Disable User
Disables a user on the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path |
Method |
Content Type |
|
|
|
Argument |
Type |
Description |
userid |
string |
The id of the user to disable |
Delete User
Deletes a user from the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to delete |
Get Groups
Retrieves a list of groups the specified user is a member of.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to retrieve groups for |
Add To Group
Adds the specified user to the specified group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to retrieve groups for |
groupid |
string |
The group to add the user to |
Status Codes
-
100 - successful
-
101 - no group specified
-
102 - group does not exist
-
103 - user does not exist
-
104 - insufficient privileges
-
105 - failed to add user to group
Remove From Group
Removes the specified user from the specified group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to retrieve groups for |
groupid |
string |
The group to remove the user from |
Status Codes
-
100 - successful
-
101 - no group specified
-
102 - group does not exist
-
103 - user does not exist
-
104 - insufficient privileges
-
105 - failed to remove user from group
Create Sub-admin
Makes a user the sub-admin of a group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to be made a sub-admin |
groupid |
string |
the group of which to make the user a sub-admin |
Status Codes
-
100 - successful
-
101 - user does not exist
-
102 - group does not exist
-
103 - unknown failure
Remove Sub-admin
Removes the sub-admin rights for the user specified from the group specified.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
the id of the user to retrieve groups for |
groupid |
string |
the group from which to remove the user’s sub-admin rights |
Status Codes
-
100 - successful
-
101 - user does not exist
-
102 - user is not a sub-admin of the group / group does not exist
-
103 - unknown failure
Get Sub-admin Groups
Returns the groups in which the user is a sub-admin.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
userid |
string |
The id of the user to retrieve sub-admin groups for |
Instruction Set For Groups
Get Groups
Retrieves a list of groups from the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
search |
string |
optional search string |
limit |
int |
optional limit value |
offset |
int |
optional offset value |
Add Group
Adds a new group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
groupid |
string |
the new group’s name |
Status Codes
-
100 - successful
-
101 - invalid input data
-
102 - group already exists
-
103 - failed to add the group
Get Group
Retrieves a list of group members.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
groupid |
string |
The group id to return members from |
Get Sub-admins
Returns sub-admins of the group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
groupid |
string |
The group id to get sub-admins for |
Delete Group
Removes a group.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
groupid |
string |
the group to delete |
Instruction Set For Apps
Get Apps
Returns a list of apps installed on the ownCloud server.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
filter |
string |
Whether to retrieve enabled or disable |
apps. Available values are |
||
and |
Get App Info
Provides information on a specific application.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
appid |
string |
The app to retrieve information for |
Get App Info Example
# Get app info for the "files" app
curl http://admin:secret@example.com/ocs/v1.php/cloud/apps/files
XML Output
<?xml version="1.0"?>
<ocs>
<meta>
<statuscode>100</statuscode>
<status>ok</status>
</meta>
<data>
<info/>
<remote>
<files>appinfo/remote.php</files>
<webdav>appinfo/remote.php</webdav>
<filesync>appinfo/filesync.php</filesync>
</remote>
<public/>
<id>files</id>
<name>Files</name>
<description>File Management</description>
<licence>AGPL</licence>
<author>Robin Appelman</author>
<require>4.9</require>
<shipped>true</shipped>
<standalone></standalone>
<default_enable></default_enable>
<types>
<element>filesystem</element>
</types>
</data>
</ocs>
Enable App
Enable an app.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
appid |
string |
The id of the app to enable |
Disable App
Disables the specified app.
The Basic Authorization HTTP header must be used to authenticate this request, using the credentials of a user who has sufficient access rights to make the request. |
Request Path | Method | Content Type |
---|---|---|
|
|
|
Argument | Type | Description |
---|---|---|
appid |
string |
The id of the app to disable |