Authentication Request
To get API access to your NEX Account, please fill out this form.
All authentication credentials are provided through OAuth2 using the API endpoint https://nexcloud.io/V1.0/Token. To begin with, you will be given a Client identification key and secret. This is used to categorise/group your API access under your organisation. You will then have a username and password for the application you are writing. So, essentially, there's a username and password for your company, and then a username and password for each separate point of use. 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/json'
The body of this POST is then your credentials for this request.
<!-- Controller request, requires:
Client Id, Client Secret,
Username, Password,
as well as the scope of the request (i.e. 'user')
* 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/json
Accept : application/json
<!-- BODY -->
{
"grant_type" : "password",
"client_id" : "mycompany",
"client_secret" : "abc123",
"username" : "myname",
"password" : "xyz456",
"scope" : "user"
}
<!-- Body explanation:
clientId = mycompany - this will be the same for all of your access
clientSecret = abc123 - this will be the same for all of your access
username = myname - this will be different for each individual user/application
password = xyz456 - this will be different for each individual user/application
scope = user - this will be the same for all of your access
-->
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 fields:
- 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 is generally the maximum period you'll 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 user can access.
<!-- RESPONSE -->
https://nexcloud.io/v1.0/Token
<!-- HEADER -->
Content-Type : application/json
<!-- The body will be formatted a JSON or XML, depending on
the Accept header you sent in the request. -->
<!-- BODY -->
{
"access_token" : "new934token1234",
"expires_in" : "12096000",
"token_type" : "Bearer",
"scope" : "user"
}
Access Limitations
The NEX API has access limits on the entire system as well as individual endpoints. The limit is how many requests are made to the API for each IP or credentials. This is to help with server load balancing, to ensure system resources aren't used wastefully, and to allow equal access to all of our API users.
We would appreciate that API access be done efficiently. Here are a few tips:
- Retrieve only the resolution required. Pre-calculated hour data and day data is provided to help with this, and to avoid access to high-resolution data when not necessary.
- Try not to spam the LiveData endpoint. This is intended for use in widgets, not for constant monitoring.
- If retrieving bulk data (i.e. for integration), access our system at longer intervals. For example data can be retrieved every quarter hour, or on-demand, instead of constant polling.
In general, we limit access to the API at an absolute maximum of 600 requests per minute per IP (or credentials). Exceeding this limit will result in an temporary IP ban for up to an hour. Particularly heavy usage is also flagged in our system for review. Please be sure to read the Terms of Service.
If you are unsure, please contact support, we are happy to help!