⚙️ITCare API

Getting started with the ITCare API

The ITCare REST API complies with the OpenAPI standard specifications.

The online documentation is available at this address: https://api.cegedim.cloud/

The basic URL is: itcare.cegedim.cloud/itcare

Get ITCare status
curl -X GET "https://itcare.cegedim.cloud/itcare/api/status"

How do I authenticate to the ITCare API ?

The ITCare API uses the OAuth 2.0 protocol for authentication and authorization. It supports the usual OAuth 2.0 scenarios such as those used for web servers and client applications.

This means that each API request must contain an Authorization header embedding an access token previously obtained through credentials.

curl -X GET "https://itcare.cegedim.cloud/itcare/api/endpoint" -H "Authorization: Bearer {token}"

How do I get an API account?

To query the ITCare API, an API account is required in order to obtain the mandatory access token.

To obtain this API account, a request must be submitted to the Cegedim Support teams.cloud Support teams by providing the following information:

  • The target organization

  • A simple description of the target usage of the API

How do I get an access token?

To obtain an access token, the client must submit a request to the endpoint /token.

The authorization server requires client authentication to issue an access_token.

Here is an example of an access_token request:

curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token " \ 
-H "Authorization: Basic base64({client_id}:{client_secret})" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Request Body: grant_type=client_credentials"

If the access_token request is allowed and valid, here is a sample response:


When the token expires, it is possible to :

  • Request a new access_token

  • Refresh the token by querying the endpoint /token

curl -X POST "https://accounts.cegedim.cloud/auth/realms/cloud/protocol/openid-connect/token" \
-H "Authorization: Basic base64({client_id}:{client_secret})" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Request Body: grant_type=refresh_token&refresh_token=****************"

What are the REST conventions of the ITCare API?

The ITCare API uses the JSON format for both input and output messages (payload).

This also includes the bodies of HTTP messages of type PUT, PATCH, POST and DELETE.

It therefore respects the standards of a REST API in terms of HTTP verb and HTTP return code.

HTTP methods and URI content type

UseHTTP methodExampleDescription

Request a list of resources


GET /resources

Returns a list of resource objects

Search through a list of resources


GET /resources?attribute=xxxx

Returns a list of resource objects filtered on the xxxx attribute

Request a resource


GET /resources/1234

Returns a resource object identified by ID 123

Create a resource


PATCH /resources/1234

Creates a resource object using the JSON attributes specified in the request body

Fully update a resource


PUT /resources/1234

Completely updates the resource object identified by ID 1234 with the JSON attributes specified in the request body

Partially update a resource


DELETE /resources/1234

Partially updates an object with the content of the request body

Delete a resource


POST /resources

Deletes the resource object identified by ID 1234

For more information about the standard RESTful implementation:

HTTP return code and response body


Request successfully processed

Varies depending on what was requested


Successfully created object

Object created


Order of creation of the object successfully processed, the request will be processed asynchronously

Empty or tracking object describing the processing of the asynchronous request


Bad query - Syntax or consistency error in the query. Must be corrected by the issuer.

Blank or indication of the error to be corrected on the client side


Unauthenticated access to the resource



Unauthorized access



Non-existent resource






Inconsistent data



Fatal API error



Service temporarily unavailable


What date/time format is used by the API?

JSON does not natively support the Date/Time format.

All parameters tagged as Date by the API are therefore strings in ISO8601 format.


Z corresponds to the time zone: +0200 for example.


For GET requests, do not forget to URL-Encode these parameters.

Can I run blank actions via the API?

Some methods allow testing of API calls without actually triggering the action in ITCare. However, the validation is still done.

To activate the Dry Run mode, simply add a custom header to your HTTP requests:

ITCare-DryRun: true

Once the server processes your request, the same custom header will be included in the response.

How do asynchronous actions work?

Some methods are asynchronous and require a delay after their invocation.

This applies to time-consuming transactions such as resource administration or reporting.

Methods that operate asynchronously will respond:

  • an HTTP return code 202

  • a body containing a tracking ID for the current asynchronous operation

Here is an example of code in Python that explains the asynchronous operation:

Launch action and get its descriptor
action = itcare.post('/api/resource', payload=my_payload)
Loop on getting its status
while action['status']=='IN_PROGRESS':
    action = itcare.get('/api/actions/{}'.format(action['id']))
Print its status
print action['status']

The status of the actions can be :




How to get started quickly with Python ?


  • Python3

  • pip (to install the SDK)

Download the following archive which contains the ITCare SDK: itcare-sdk.tar.gz

Unzip it and enter the directory.

Run the following commands to install the ITCare Python SDK.

pip install pyoidcclient
pip install itcare

Create your first script

# lib import
from itcare import ITCareService
# API Account on ITCare
# Create API client
itcare = ITCareService(url="https://itcare.cegedim.cloud/itcare", oidc_provider="https://accounts.cegedim.cloud/auth/realms/cloud", oidc_client_id=ITCARE_USERNAME, oidc_client_secret=ITCARE_PASSWORD)
# get instances
instances = itcare.get('/api/instances')
for instance in instances:
  print("Instance {}".format(instance.get("name")))

Last updated