API v3 overview
Retrieve API Key and Secret
Go to Manage > Developers on the Cloud4Wi dashboard, make sure that you are in the APIs tab, and create your service under API v3.
Select the "Public app" role if you are generating access data for the mobile app. Otherwise, select the “Organization Manager” role.
Also, select the scopes with the related permission (Read or Write), according to the pieces of information you want API to access. The following information about scopes may help you:
- “Organization” is the largest scope on the platform and contains all other scopes. Use it if you want to provide full access.
- The mobile app requires the Customer Read, Customer Write, and Organization Settings Read scopes to work properly.
You can create multiple API keys and secrets, and you can edit or delete them at any time.
Using your clientKey and clientSecret you can request for a token by calling the dedicated method (note: replace asterisks with your client key and secret)
If the client key and secret are correct, then the API will return a JWT token.
To access the resources, you have to add the token in the Authorization Header as Bearer (see the example below)
The JWT token expires after one day; to get a new one, restart and call again /v1/sts/login/services.
All endpoints will respond with an HTTP status code (find more details here):
- 200: Successful request
- 201: The request has been accepted
- 401: Unauthorised, invalid client key or secret
- 403: Forbidden, the service is not authorized to access the resource, or the token is invalid/expired
- 409: Conflict, the request had semantic errors or invalid parameters
- 404: The resource does not exist
- 410: This endpoint has been revoked or removed
- 429: Too many requests, rate limit exceeded
- 500: Uncaught application error
Error responses also include an error message where relevant.
Find below the example of an error message:
APIs Rate Limits
All versions of APIs are subject to limits:
- burst: 60 requests/minute
- daily: 15.000 requests/day
Where can I find the 'iss'?
The token used has the JWT format (https://en.wikipedia.org/wiki/JSON_Web_Token).
You can find the iss inside the payload of the JWT after you have decrypted it.
Example of decrypted JWT
How to check the rate limit?
In each API response, you can find some HTTP headers containing two types of limits.
Requests Rate Limits
Limits are on the number of requests to APIs.
X-Ratelimit-Limit-Minute: limit per minute
X-Ratelimit-Remaining-Minute: remaining requests per minute
X-Ratelimit-Limit-Day: limit per day
X-Ratelimit-Remaining-Day: remaining requests per day
Objects Rate Limits
Limits are on the number of objects elaborated (created/returned/edited/delete) through the APIs.
X-Ratelimit-Limit-<object>-Day: limit per object</object>
X-Ratelimit-Remaining-<object>-Day: remaining objects per day</object>
Where <object> is the object to which the limit refers</object>
If you reach any of the limits, then the API will return an HTTP/1.1 429 status code to the client with the following JSON body:
What is the 'cid'?
The 'cid' a string that univocally identifies an object.
It is related to the type of the object of the request, for example in the API
the 'cid' is the identifier of the customer object
Where can I find the 'cid' of the organization?
You can find your organization 'cid' in the Admin Panel in the section /services
How to use the 'sid' in the search APIs?
You can use the 'sid' (scroll id) to retrieve a large number of results from a search request.
You have to execute an initial search request without the 'sid' to initialize the scroll session. The API will return the 'sid' parameter in the response.
As a second step, you have to set the received 'sid' along with the following requests. This response will generate a new 'sid', that you can use to retrieve the next batch of results, and so on.
You can repeat this process in a loop until the API will not return any result.
The maximum time interval between 2 requests is 60 seconds; after that interval, the 'sid' expires, and the API will not return any result until you submit a new 'sid'.