Nextcloud API

Nextcloud Provisioning API

Overview

The Provisioning API enables external systems to create, edit, delete and query user attributes, manage groups, set quotas, query storage, and manage apps. Enabled by default. Uses the OCS API endpoint format.

Base URL: https://nextcloud.example.com/ocs/v1.php/cloud

Auth: Basic HTTP Auth (admin username:password) + OCS-APIRequest header

Headers (required for ALL calls):

• Authorization: Basic <base64(admin:password)>
• OCS-APIRequest: true
• POST requests also require Content-Type: application/x-www-form-urlencoded

Output format: XML by default. Append ?format=json for JSON.

Users

Add a New User

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "userid=newuser" \
  -d "password=SecurePass123!" \
  -d "displayName=New User" \
  -d "email=newuser@example.com" \
  -d "groups[]=admin" \
  -d "groups[]=group1" \
  -d "quota=10GB"

Status codes: 100=ok, 101=invalid, 102=already exists, 104=group missing

List Users

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users?search=filter&limit=100&offset=0" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" | python3 -c "import sys, xml.etree.ElementTree as ET; print('\n'.join(e.text for e in ET.parse(sys.stdin).findall('.//users/element')))"

Get Single User

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" | python3 -c "
import sys, xml.etree.ElementTree as ET
root = ET.parse(sys.stdin).find('.//data')
for child in root:
    if child.tag == 'groups':
        print(f'{child.tag}: {[e.text for e in child]}')
    elif child.text and child.text.strip():
        print(f'{child.tag}: {child.text.strip()}')
"

Returns: enabled, id, quota, email, displayname, phone, address, website, twitter, groups.

Edit User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=email" \
  -d "value=newemail@example.com"

Editable fields: email, quota, displayname, phone, address, website, twitter, password. Admin can set quota; users can only edit their own email, displayname, password.

Disable User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/disable" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Enable User

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/enable" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Delete User

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Get User Groups

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Add User to Group

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Remove User from Group

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Promote to Subadmin

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=group"

Demote from Subadmin

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=oldgroup"

Resend Welcome Email

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/users/newuser/welcome" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Groups

List Groups

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups?search=adm&limit=50&offset=0" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Create Group

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/groups" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "groupid=newgroup"

Status codes: 100=ok, 101=invalid, 102=already exists

Get Group Members

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups/admin" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Returns list of users in the group.

Get Group Subadmins

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup/subadmins" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Edit Group Display Name

curl -X PUT "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "key=displayname" \
  -d "value=My Group Name"

Delete Group

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/groups/mygroup" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Does not delete users in the group. Cannot delete the admin group.

Apps

List Apps

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/apps?filter=enabled" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Filter: enabled, disabled, or omit for all.

Get App Info

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Enable App

curl -X POST "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files_texteditor" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Disable App

curl -X DELETE "https://nextcloud.example.com/ocs/v1.php/cloud/apps/files_texteditor" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Editable Fields Reference

Available via API:

curl -X GET "https://nextcloud.example.com/ocs/v1.php/cloud/user/fields" \
  -H "Authorization: Basic $(echo -n 'admin:password' | base64)" \
  -H "OCS-APIRequest: true"

Returns: displayname, email, phone, address, website, twitter.

Error Handling

Common Mistakes

• Missing OCS-APIRequest header — Every request needs OCS-APIRequest: true. Without it, requests return empty responses or 404.
• Wrong base path — Use ocs/v1.php/cloud/, not ocs/v2.php/. The v2 path is for the Share API, not Provisioning.
• Password with welcome email — Creating a user without a password AND without an email sends no welcome email. Always provide email when omitting password.
• XML vs JSON — Default output is XML. For machine parsing, always append ?format=json. Python XML parsing of Nextcloud responses can fail on missing tags.
• Group deletion — Deleting a group does not delete its users. Users remain ungrouped.
• Cannot delete admin group — The admin group is protected. You cannot remove users from it via API.
• POST needs form-urlencoded — POST/PUT requests must use Content-Type: application/x-www-form-urlencoded. JSON body is not accepted by the OCS API.
• Quota format — unlimited works but 0 does not mean unlimited. Use -3 (negative bytes) for unlimited in the API field.

Tips

• JSON output — Append ?format=json to any endpoint URL for JSON responses instead of XML
• OCS-APIRequest header is mandatory — Without it, requests return empty or 404
• Base URL path — ocs/v1.php/cloud/ (not ocs/v2.php/ — that's the Share API)
• Password-on-create — Leave password empty and provide email to send welcome email with password setup link
• Groups array — Use groups[]=group1 & groups[]=group2 for multiple groups in create
• Quota format — Supports values like 1GB, 500MB, unlimited (or just enter none for unlimited)
• Basic auth — Use the Nextcloud admin user, not an OCC system user
• OCC alternative — For bulk operations or complex config, occ command inside the pod is more powerful:

  kubectl exec deploy/nextcloud -- php occ user:list
  kubectl exec deploy/nextcloud -- php occ group:add mygroup
  kubectl exec deploy/nextcloud -- php occ user:add --display-name="Layla Smith" --group="users" layla
  

• App IDs — App ID for the Provisioning API is provisioning_api (enabled by default); remove it to disable the API
• Rate limiting — Nextcloud has no built-in API rate limiting. Add at reverse proxy if needed.