API v3 overview

Beta program

At this time, v3 includes only a subset of APIs.

We are publishing new endpoints every product release. If you are interested in using the new APIs, please contact our team!

Cloud4Wi REST APIs v3 provide you with more scalability and improved performances, and they introduce a new authentication method. Find more technical details below.

 

Retrieve API Key and Secret

On your Cloud4Wi Dashboard, go to Cloud4Wi APIs apps form the Settings > Marketplace page.

Create a new Service enabling the Read / Write scopes, according to your needs.

Finally, you can see the API Key and Secret clicking on the view icon.


Authentication

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)

curl -X POST \
 https://explore.cloud4wi.com/v1/sts/login/services \
 -H 'Cache-Control: no-cache' \
 -H 'Content-Type: application/json' \
 -H 'accept: application/json' \
 -d '{
 "clientKey":"ck-********-****-****-****-************",
 "clientSecret":"********************************"
}'

If the client key and secret are correct, then the API will return a JWT token.

{"token":[[JWT_TOKEN]]"}

To access the resources, you have to put the token in the Authorization Header as Bearer (see the example below)

curl -X GET \
 'https://explore.cloud4wi.com/v2/customers/organizations/[[CID]]?sortBy=created_absolute&sortReverse=false' \
 -H 'Authorization: Bearer [[JWT_TOKEN]]' \
 -H 'Cache-Control: no-cache' \
 -H 'accept: application/json'

The JWT token expires after one day; to get a new one, restart and call again /v1/sts/login/services.

AuthN/AuthZ Flow



API Responses

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:

{     "message": "Access Denied"
}

APIs Rate Limits

All versions of APIs are subject to limits:

  • burst: 60 requests/minute
  • daily: 15.000 requests/day

FAQ

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

header:
{
  "alg": "HS256"
}

payload:
{
  "aud": "service",
  "iss": "srv-11111111-zzzz-yyyy-xxxx-2222222",
  "exp": 1574173580,
  "iat": 1574087186
}

signature:
HMACSHA256(
  base64UrlEncode(header) + "." +
  base64UrlEncode(payload),
  secret
)

How to check the rate limit?

In the 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:

{ 
    "message": "API rate limit exceeded" 
}

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

/v1/customers/[[CID]]

the 'cid' is the identifier of the customer.

Where can I find the 'cid' of the organization?

You can find your organization 'cid' in the Admin Panel in the section /services

mceclip0.png


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 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'.

Examples

first request

Request:

GET customers/organizations/[[CID]]?size=100&hasEmail=true&hasPhone=false&ageVerification=true

Response:

{
    "generated": "2019-11-20T16:56:06Z",
    "totalCount": 216,
    "count": 100,
    "sId": "c5ecaa82e6b01e6dcb8d059ede66b8fe32ca25cfb376129fda99585a91e41253",
    "customers": [
      ...
    ]
}

following requests

GET customers/organizations/[[CID]]?sId=c5ecaa82e6b01e6dcb8d059ede66b8fe32ca25cfb376129fda99585a91e41253

Response:

{
    "generated": "2019-11-20T16:56:30Z",
    "totalCount": 216,
    "count": 100,
    "sId": "36955899909af957fc8a6f8ba7c14ea6c295ce83581a7850ad89b40afff75a7a",
    "customers": [
      ...
    ]
}