API documentation DRAFT
The OCS Registration API allows you to register for an account, check the status of the registration and get initial login credentials from within clients.
The base URL for all calls to the API is: <nextcloud_base_url>/ocs/v2.php/apps/registration/api/v1
If cloud providers implement that api they need to provide all of the endpoints described in the following.
All calls to OCS endpoints require the OCS-APIRequest header to be set to true.
This API documentation is still a DRAFT and still can change
POST /validate
Verify that user data is valid before sending a registration request
Parameters
- username - (string) unique username on the nextcloud instance
- displayname - (string) display name of the user
- email - (string) email of the user
Response data
- username - (string)
- displayname - (string)
- email - (string)
Statuscodes
- 200 - Data is valid
- 400 - Data is invalid (see OCS message for details)
POST /register
Parameters
- username - (string) unique username on the nextcloud instance
- displayname - (string) display name of the user
- email - (string) email of the user
- password - (string) password of the user
Response data
- secret - (string) secret to allow the client to check the status of the registration
- registrationStatus - (int) Status of the registration - message - (string) Message about the current state of the registration
Registration status
- 0 - Registration complete (ready to login)
- 1 - Further steps required (see message for details)
- 2 - Registration already exists
Statuscodes
- 200 - Registration successful
- 400 - Registration failed (see OCS message for details)
POST /status
Parameters
- clientSecret - (string) client secret to identify
Response data
- cloudUrl - (string) Url of the Nextcloud instance to authenticate with
- appPassword - (string) Generated app password the client to login (optional)
- registrationStatus - (int) Status of the registration
Registration status
- 0 - Registration complete (ready to login)
- 1 - Further steps required (see message for details)
- 2 - Registration already exists
Statuscodes
- 200 - Success (See registrationStatus for further details)
- 404 - Registration not found
Example usage (OUTDATED)
Verify that the data is valid
curl http://localhost:8080/ocs/v1.php/registration/v1/validate\?format\=json \
-H "OCS-APIRequest:true" -v \
--data "username=foobar&displayname=foobar&email=foobar@example.com"
Valid data
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"username": "foobar",
"displayname": "foobar",
"email": "foobar@example.com"
}
}
}
Invalid data
{
"ocs": {
"meta": {
"status": "failure",
"statuscode": 999,
"message": "A user has already taken this email, maybe you already have an account?",
"totalitems": "",
"itemsperpage": ""
},
"data": []
}
}
Create a new registration request
curl http://localhost:8080/ocs/v1.php/registration/v1/register\?format\=json \
-H "OCS-APIRequest:true" -v \
--data "username=foobar&displayname=foobar&email=foobar@example.com&password=foobar"
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"message": "Your registration is pending. Please confirm your email address.",
"status": 1,
"secret": "L2qdLAtrJTx499ErjwkwnZqGmLdm3Acp"
}
}
}
Check the state of the registration
curl http://localhost:8080/ocs/v1.php/registration/v1/status\?format\=json \
-H "OCS-APIRequest:true" --data \
"clientSecret=L2qdLAtrJTx499ErjwkwnZqGmLdm3Acp"
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"status": 1,
"message": "Your registration is pending. Please confirm your email address."
}
}
}
Confirm by opening the link from the mail
curl http://localhost:8080/index.php/apps/registration/verify/RDTK1V
Check status again
curl http://localhost:8080/ocs/v1.php/registration/v1/status\?format\=json \
-H "OCS-APIRequest:true" --data\
"clientSecret=L2qdLAtrJTx499ErjwkwnZqGmLdm3Acp"
{
"ocs": {
"meta": {
"status": "ok",
"statuscode": 100,
"message": "OK",
"totalitems": "",
"itemsperpage": ""
},
"data": {
"status": 0,
"appPassword": "PsaBw-Xordt-yGGjZ-TARCe-RRJFW",
"cloudUrl": "https://nextcloud.example.com"
}
}
}
Check status again
curl http://localhost:8080/ocs/v1.php/registration/v1/status\?format\=json \
-H "OCS-APIRequest:true" --data \
"clientSecret=L2qdLAtrJTx499ErjwkwnZqGmLdm3Acp"
{
"ocs": {
"meta": {
"status": "failure",
"statuscode": 998,
"message": "No pending registration.",
"totalitems": "",
"itemsperpage": ""
},
"data": []
}
}