Skip to main content

Using the API

The IAM (Identity and Access Management) API share a common behavior.

Organizations and spaces​

The API operate within the scope of an organization or a space: the presence of the terms spaces or organisations in the URL distinguishes the scope of the requests.

The URL to act at the organization level takes the form: ...iam/organisations/"organisationId"/

The one to act on a space takes the form: ...iam/spaces/"spaceId"/

The access token​

The API require a valid access token to work.

It is of the bearer type (in accordance with RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage).

Example of an access token request

export REGION="myregion"
curl -X POST https://api.$REGION.numspot.com/iam/token \
-H 'Accept: */*' \
-H 'Authorization: Basic <base64([Id:secret])>' \
-H 'Content-Length: 57' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-d 'grant_type=client_credentials&scope=openid+offline_access'

Once the token is returned, it is added to the other requests in this form:

Adding an access token to the header of a Curl request

curl  ... -H "Authorization: Bearer {token}"

Pagination for lists​

Requests that may return an indeterminate number of items provide pagination.

Using pagination is recommended in order to avoid placing too high a load on the system.

Pagination takes the following form:

  • by default, the page is limited to 30 items;
  • the page[size] parameter sets the number of items per page;
  • the page[nextToken] parameter is returned in the response and must be added to the next request;
  • information to obtain the next page is provided in the response of the first page.

Example of a request for a list with pagination

        page[size]=30&page[nextToken]=bee04e3c-850f-4f25-8597-04ba43b24877
   (encoded format: /organisations?page%5BnextToken%5D=bee04e3c-850f-4f25-8597-04ba43b24877)

The body of the response contains a token to provide in order to obtain the next part:

Example of a response

..'nextPageToken': '287ccb59-0c94-4c90-9798-02c9179f5a3f'

This token must be added as a parameter to the second request. If a third page is required, the second page provides a new page token.

'nextPageToken=287ccb59-0c94-4c90-9798-02c9179f5a3f'

#ligne complete
https://...?page%5Bsize%5D=30&page%5BnextToken%5D=bee04e3c-850f-4f25-8597-04ba43b24877

The last page does not contain this token.

Conventions​

The URL in the examples are sometimes shown with terms between braces: organisationId, userId, and so on. These expressions must be replaced with the identifiers of the entities being handled.

The identifiers take the form of a UUID (Universally Unique Identifier, see RFC 4122).

Asynchronous processing​

Creating a space can take several minutes. Querying a space returns a "status" key containing the state of the space. The status can take four values:

  • QUEUED;
  • RUNNING;
  • READY;
  • FAILED.

The nominal state of a space is READY. You must therefore wait for its creation to complete before launching other operations.

Identifier mapping​

All the entities being handled are identified by a UUID. The API work from these UUID. To obtain the corresponding name, you must use the resource information retrieval API (for example: retrieve the information of a space or a user by its identifier).

Cette page vous a-t-elle été utile ?