The InterCloud API uses OpenID Connect protocol for authentication.

API Access tokens can be obtained by two different ways :

Access tokens

API access tokens are generated programatically via the (/auth/token) route. More information can be found in the OIDC section of the documentation.

Personal Access Tokens

Personal Access Tokens are managed in the Account Section of the InterCloud portal or via the (/auth/token) route. They best suited for scripts and single-use applications. Your PATs carry many privileges, so be sure to keep them secret. Do not share your tokens in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via Bearer Authentication. Regardless of the way they've been generated with, access token are used the same way : They should be provided as a Bearer value through an "Authorization" header: -H "Authorization: Bearer UabvhLHcRr2dF9zhun4JBQ"

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail, except the token creation requests.

The InterCloud API features Cross-Origin Resource Sharing (CORS) implemented in compliance with W3C spec. And that allows cross-domain communication from the browser. All responses have a wildcard same-origin which makes them completely public and accessible to everyone, including any code on any site.

The InterCloud API follows the REST (REpresentational State Transfer) design pattern. This means that the CRUD (Create, Read, Update, and Delete) operations are specified by using HTTP methods. These are referred to as RESTful verbs.

In addition to the fields provided by the dataset owner, InterCloud also provides a number of useful system fields you can make use of. They’re very useful for detecting when datasets have changed.

System fields are always included by default.

The :id field is an Version 4 UUID. A Version 4 UUID is a universally unique identifier that is generated using random numbers. The Version 4 UUIDs produced by this site were generated using a secure random number generator.

InterCloud API version is defined by the api-version header returned by any the api call.

HTTP/2.0 200 OK
date: Wed, 10 Jul 2019 09:27:04 GMT
content-type: application/json; charset=utf-8
content-length: 138
api-version: 1.0

TBC

Requests that return collection of resources will be paginated to 50 items by default. You can specify further pages with the ?page parameter. You can also set a custom page size up to 100 with the ?limit parameter (100 is the maximum item per page you can fetch).

curl 'https://console.intercloud.io/users?page=2&limit=100'

Note that page numbering is 1-based and that omitting the ?page parameter (or setting it to 0) will return the first page.

The content-range header includes pagination information:

Content-Range: [Index of the first element of the page - index of the last element of the page / Total number of elements in the request]

For example:

Content-Range: 0-4/10

The Link header includes pagination information:

 Link: <%2Fusers?page=1&limit=2>; rel="first",
       <%2Fusers?page=1&limit=2>; rel="previous",
       <%2Fusers?page=3&limit=2>; rel="next",
       <%2Fusers?page=5&limit=2>; rel="last"

The example includes a line break for readability.

This Link response header contains one or more Hypermedia link relations, some of which may require expansion as URI templates.

The possible rel values are:

InterCloud REST API uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• 2xx (Successful): The request was successfully received, understood, and accepted
• 3xx (Redirection): Further action needs to be taken in order to complete the request
• 4xx (Client Error): The request contains bad syntax or cannot be fulfilled
• 5xx (Server Error): The server failed to fulfill an apparently valid request

Some 4xx errors that could be handled programmatically include an error message and an error code that briefly explains the reported error.

Here is some specific codes explained:

IRN stands for InterCloud Resource Name. An IRN is an unique identifier (string format) that helps in a specific resource identification. It gathers the resource family information, the resource owner and a unique identifier. Please find below an example of IRN:

irn:geoentrypoint:1hv0g4w1k2rkg::t2cxj9

Endpoints for organisations management

Endpoints for organisations pool management

Endpoints for organisations capacity management

Endpoints for audit-logs management

Endpoints for users management

Endpoints for OpenID Connect management

Endpoints for user access right and permission management

Endpoints for edges management

Endpoints for groups management

Endpoints for legacy connectors management

Endpoints for new connectors flow management