Detailed manual for the CareCloud API authentication.
Enterprise interface HTTP Bearer authentication
If integrating a mobile application or a customer portal, please check Customer Interface HTTP Bearer authentication.
Bearer authentication method
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. "Bearer authentication" can be understood as "giving access to the bearer of this token." The bearer token is a cryptic string, usually generated by the server in response to a login request. The client must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>
As described above, you need a bearer token for authentication through the HTTP Bearer method. In CareCloud API, you can get this token as a response from a successful call of the user login action method.
Bearer token validity has a default value of 7 hours. Every project can customize the validity of the bearer token if needed.
For a successful login, you will need the ID of the external application and user credentials.
If you already have all the information, you can continue the Authentication process.
If you miss any parameters, please check the User credential and External applications sections below.
If you don't have direct access to CareCloud, please contact the responsible person in your organization to provide credentials and an external application ID.
User credentials
If you miss user credentials, you can create or get them in the Users of CDP administration section.
Complete CareCloud user setup is available in:
System configuration > User authorization > Users
Adding a new user in CDP CareCloud administration.
CareCloud API is available only for users with User Group
webservice.
External applications
The external application represents an application that wants to (or already does) communicate with CPD CareCloud API. Every system must be identified in CareCloud API, so we use the external application ID.
It could be one of the following examples:
- The Cash register system completes the customer's purchase process
- The E-shop displays and edits the data of various customers
- The Production system synchronizes customer purchases
- The Business Intelligence tool creates reports for company management
If you need an external application ID, you can get an existing ID in CDP CareCloud administration in the section External Applications:
System configuration > External applications
External application overview in CDP CareCloud administration.
Or you can add a new external application to the CDP CareCloud by using the following form in the same section:
Adding a new external application in CDP CareCloud administration.
For CareCloud API usage, please copy and use only the Encoded ID.
If you don't have direct access to CareCloud, please contact the responsible person in your organization to provide credentials and an external application ID.
Authentication process
You can continue with the User login API call if you have all the mandatory parameters.
Please don't forget to replace the project Sandbox domain with the domain of the CareCloud installation.
POST https://sandbox.crmcarecloud.com/webservice/rest-api/enterprise-interface/v1.0/users/actions/login
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
{
"user_external_application_id": "89d1a6111b3fb6e74665d948",
"login": "fabulous_user",
"password": "password_example"
}
The bearer token is provided in the response with other information about the user:
{
"data": {
"bearer_token": "09359095c5da43c7ae11e710eabce49418715a6a",
"valid_to": "2023-01-04 10:31:56",
"user": {
"user_id": "838b73aacb5ac326cec4030c80",
"login": "fabulous_user",
"first_name": "Faboulous",
"last_name": "Legend",
"email": "[email protected]",
"phone": 420123828931,
"user_role_id": "86e05affc7a7befcd513ab400",
"store_id": "86e05affc7a7abecd513ab400"
}
}
}
The next step is to add a bearer token to every CareCloud API call with the following syntax:
GET https://sandbox.crmcarecloud.com/webservice/rest-api/enterprise-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 09359095c5da43c7ae11e710eabce49418715a6a
Successful response :
HTTP/1.1 200 OK
Date: Mon, 22 Jul 2019 11:54:39 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"customers": [
{
"customer_id": "8ea6abece4cd0a4ded0a29f093",
"personal_information": {
"gender": 1,
"first_name": "John",
"last_name": "Smith",
"birthdate": "985-02-12",
"email": "[email protected]",
"phone": "420523828931",
"language_id": "en",
"store_id": "8bed991c68a4",
"address": {
"address1": "Old Town Square",
"address2": "34",
"address3": "",
"address4": "",
"address5": "",
"address6": "",
"address7": "",
"zip": "11000",
"city": "Prague 1",
"country_code": "cz"
},
"agreement": {
"agreement_gtc": 1,
"agreement_profiling": 1,
"agreement_marketing_communication": 1,
"custom_agreements": [
{
"agreement_id": "89ce2a1b9b01f5c939fb1e20cd",
"agreement_value": 2
}
]
}
},
"last_change": "2019-06-23 11:47:22",
"state": 1
}
],
"total_items": 1
}
}
Customer Interface HTTP Bearer authentication
If you integrate an e-shop, POS, or Business Intelligence tool, please check Enterprise interface HTTP Bearer authentication
Bearer authentication method
Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. "Bearer authentication" can be understood as "giving access to the bearer of this token." The bearer token is a cryptic string, generated by the server. The client must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <access_token_id>
This process will result in access to CareCloud API for one installation of an application that is (or is not) logged in by a customer. This customer can see only his data and has no available data of other customers.
External applications
The external application represents an application that wants to (or already does) communicate with CPD CareCloud API. Every system must be identified in CareCloud API, so we use the external application ID.
It could be one of the following examples:
- Mobile application
- Customer Portal
- Self-service kiosk
If you need an external application ID, you can get an existing ID in CDP CareCloud administration in the section External Applications:
System configuration > External applications
External application overview in CDP CareCloud administration.
Or you can add a new external application to the CDP CareCloud by using the following form in the same section:
Adding a new external application in CDP CareCloud administration.
For CareCloud API usage, please copy and use only the Encoded ID.
If you don't have direct access to CareCloud, please contact the responsible person in your organization to provide credentials and an external application ID.
Authentication process
To access a CareCloud API, creating an access token using the method POST /tokens is necessary. Creating an access token does not require any authentication method in the HTTP header. The request has the following structure:
POST https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/tokens
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
{
"device": {
"device_id": "123456",
"device_system": "OSX",
"device_name": "Test device",
"device_type": "iPhone"
},
"setup": {
"language_id": "en",
"allowed_gps": true,
"allowed_notifications": false
},
"external_application_id": "82de12eb8b138791e678fd11c3",
"push_token": "4f7f658bfa7a5959e093590"
}
Parameter
device_idmust be unique in every access token creation. Otherwise, it can cause problems when a customer uses multiple devices or web browsers.
Properly sent request returns an access token:
{
"data": {
"token_id": "4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf"
}
}
The token_id value represents an access token that must be used in every request requiring authentication. Please place the value from token_id into Authentication header following way:
Authorization: Bearer 4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf
The access token is required in the Authentication header even if a customer is not logged in.
The access token doesn't have a limited validity. The only way to make the token invalid is to create a new token for the same external application and the same device (The parameters device_id and external_application_id match existing ID in the CareCloud database).
The next step of logging a customer is optional. If you don't need to log in as a customer, please continue to the next step
After successful identification of your installation on a device, you can log in to your customer with the following method [POST] /tokens/{token_id}/actions/login. Remember to set the{token_id} in the HTTP Authorization header. Afterward, please put the right customer credentials into the request's body.
Do not copy the credentials below. Code is just an example of a method used.
POST https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/tokens/4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf/actions/login
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 09359095c5da43c7ae11e710eabce49418715a6a
{
"login_type": "email",
"login_value": "[email protected]",
"password": "password_example"
}
You will receive the customer_id of the logged-in customer as a positive response with the appropriate status code.
{
"data":{
"customer_id":"8ea6abece4cd0a4ded0a29f093"
}
}
After a successful customer login, you can do an API call on the endpoints requiring the logged-in customer. Like in the customer example:
GET https://sandbox.crmcarecloud.com/webservice/rest-api/customer-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 4d8121dea8ae3c7b7fc66e6924ecc466dc7aa13e299ac757d87533ab2630f31bd906aadf
Successful response :
HTTP/1.1 200 OK
Date: Mon, 22 Jul 2019 11:54:39 GMT
Content-Type: application/json; charset=utf-8
{
"data": {
"customers": [
{
"customer_id": "8ea6abece4cd0a4ded0a29f093",
"personal_information": {
"gender": 1,
"first_name": "John",
"last_name": "Smith",
"birthdate": "985-02-12",
"email": "[email protected]",
"phone": "420523828931",
"language_id": "en",
"store_id": "8bed991c68a4",
"address": {
"address1": "Old Town Square",
"address2": "34",
"address3": "",
"address4": "",
"address5": "",
"address6": "",
"address7": "",
"zip": "11000",
"city": "Prague 1",
"country_code": "cz"
},
"agreement": {
"agreement_gtc": 1,
"agreement_profiling": 1,
"agreement_marketing_communication": 1,
"custom_agreements": [
{
"agreement_id": "89ce2a1b9b01f5c939fb1e20cd",
"agreement_value": 2
}
]
}
},
"last_change": "2019-06-23 11:47:22",
"state": 1
}
],
"total_items": 1
}
}