Authentication for a Controller is done in the similar way as documented on the general Authentication page, in that Tokens must be requested and renewed using your specific credentials.
The difference for a controller is that the token is requested using a Controller ID and Controller Secret, instead of a Username and Password.
All authentication credentials are provided through OAuth2 using the API endpoint https://nexcloud.io/V1.0/Token. To begin with, all your products will have a specific Client identification key and secret. This is used to categorise/group all your Devices together through your organisation's client credentials. Additionally, each individual Controller that connects to the API will have its own Controller Id and secret. So, essentially, there's a username and password for your company, and then a username and password for each of your Controllers. By correctly providing these to the API, you will be given an API token with which to communicate to the API.
The easiest way to retrieve an access token is by using a POST request to https://nexcloud.io/v1.0/Token, along with the header
'Content-Type : application/x-www-form-urlencoded'
The body of this post is then your credentials for this request.
See:
- Wikipedia: Submitting web forms (external link)
- Wikipedia: The application/x-www-form-urlencoded type (external link)
<!-- Controller request, requires:
Client Id, Client Secret,
Controller Id, Controller Secret,
as well as the scope of the request (ie. 'controller')
* Note that these values are just an example,
you will need to substitute your actual values into this. *
-->
<!-- POST -->
https://nexcloud.io/v1.0/Token
<!-- HEADER -->
Content-Type : application/x-www-form-urlencoded
Accept : application/json
<!-- BODY -->
grant_type=client_credentials&client_id=5a5b&client_secret=abc123&controller_id=111aa
&controller_secret=456&scope=controller
<!-- Body explanation:
clientId = 5a5b - this will be the same for all of your products
& clientSecret = abc123 - this will be the same for all of your products
& controllerId = 111aa - this will be different for each physical object
& controllerSecret = 456 - this will be different for each physical object
& scope = controller - this will be the same for all of your products
-->
Authentication Response
After sending the request, you will receive a response. If everything is in order, your request will be successful and you will receive a response like this.
The body will be formatted as JSON or XML depending on your Accept header in the request. It will contain four members:
- The access token.
- The expires in value, which is how long the value will be valid for in seconds. This is not constant between all token types, so make sure you check your token expiry time. The example token here has a 2 week period for use, which would be the maximum period you'll ever see.
- The token type value, which will be bearer. This is simply to tell you that you must attach this token to each request to use it.
- The scope of the token, which is that it can access everything a controller can access.
<!-- RESPONSE -->
https://nexcloud.io/v1.0/Token
<!-- HEADER -->
Content-Type : application/json
<!-- BODY -->
response :
access_token : new934token1234
expires_in : 12096000
token_type : Bearer
scope : controller