nextcloud-registration-api-test.md

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": []
  }
}