Authentication

HTTP Bearer authentication

Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The name "Bearer authentication" can be understood as "give 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>

Enterprise interface HTTP Bearer authentication

As described below, for authentication through HTTP Bearer, you will need a bearer token.
In REST API, you can get this token as a response from a successful call of user login action method.
For a successful login, you will need the ID of the external application and user credentials. If you miss any of these, please contact your account manager.

User login request :

POST https://<projectURL>/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 ": "4d9495b4e723e7a",
  "login": "example@crmcarecloud.com",
  "password": "password_example"
}

Bearer token in response of the method:

{
    "data":{
        "bearer_token":"09359095c5da43c7ae11e710eabce49"
    }
}

After you successfully got your bearer token, please add it to every REST API call in the Enterprise interface with the following syntax:

GET http:<projectURL>/rest-api/customer-interface/v1.0/customers
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Bearer 09359095c5da43c7ae11e710eabce49

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": "happy_customer@crmcarecloud.com",
                    "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": "custom_agreement_id",
                                "agreement_value": 2
                            }
                        ]
                    }
                },
                "last_change": "2019-06-23 11:47:22",
                "state": 1
            }
        ],
        "total_items": 1
    }
}

HTTP Basic autentication

HTTP Basic authentication method (https://en.wikipedia.org/wiki/Basic_access_authentication) has to be used to login to API successfully. There are two options to authenticate depending on your kind of integration:

Enterprise interface authentication

HTTP BASIC authentication is deprecated for the Enterprise interface. Please look at HTTP Bearer authentification for the Enterprise interface.

User name and password have to be used for Enterprise interface authentication. Credentials are BASE64 encoded during HTTP basic authentication. HTTP header will look like the example below.

Before BASE64 encoding:

Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic <user name>:<password>

After BASE64 encoding:

Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic Zm9vOmJhcg==

The password is composed of two parts:

  • User password hashed with MD5 algorithm
  • Time in format YYYYMMDDHH (UTC)

All parts are connected and hashed with SHA-256 algorithm (implementation in PHP):

hash('sha256',md5("password")."2019040112"); 

Result:

string(64) "c0c0d92061deb13bf34570e513229368979708efcdbc80b8d881e7ef03461a6c"


Customer interface authentication

User name and token (provided by resource tokens) are used for Customer interface client authentication. Credentials are BASE64 encoded. HTTP header will look like the example below.

Before BASE64 encoding:

GET / HTTP/1.1
Host: project.carecloud.cz
Authorization: Basic <user name>:69dfa909171f15783d92877d86d114f8c49a50a8e15bdf4c280ba46cdb3a3d49c1288218

After BASE64 encoding:

GET / HTTP/1.1
Host: project.carecloud.cz
Authorization: Basic Zm9vOmJhcg==

For user name, please ask your account manager. If you don't know how to get token, please read authentication use case here