Tokens

Management of token resources. Tokens are used for identification of the application installation on a device and for setup of basic application parameters (permissions, language, notification identification).

Warning: Tokens resource is available only in Customer interface.

Available methods

All available methods for resource tokens.

HTTP method Endpoint Description
[badge-green POST] /tokens Create a token, setup of the client's application
[badge-grey PUT] /tokens/{token_id} Update a push token and installation setup

Actions

Action methods for resource tokens.

HTTP method Endpoint Description
[badge-green POST] /tokens/{token_id}/actions/login Login of a customer to the client's application
[badge-green POST] /tokens/{token_id}/actions/logout Logout of a customer from client's application
[badge-green POST] /tokens/{token_id}/actions/social-network-login Login of a customer to the client's application via social network
[badge-green POST] /tokens/{token_id}/actions/send-password-setup-email This action sends an email, that contains a link to set up a password. This method can be used in case of forgotten password or if a customer has no password.
[badge-blue GET] /tokens/{token_id}/actions/auth-token This action returns authentication token for specific external application.

Note: The process of authentication and login to customer account using the HTTP methods [badge-green POST] /tokens and [badge-green POST] /tokens/{token_id}/actions/login is desribed in the section Use cases.

Create a token

Create a token and setup of the client's application
[badge-green POST] /tokens

Note: When creating a new token, HTTP header doesn't contain token_id in authentication part.

Warning: We highly recommend filling all identifications in tokens resource (device and application) to avoid problems if multiple applications use CareCloud REST API on one device.

Request

Parameter name Type Description Mandatory (Yes/No)
device Device Structure describes client's device Yes
setup Setup Setup of a client's device Yes
external_application_id string Id of the customer-external-application resource No
push_token string Push notification token (Apple or Google) No

Response

Status code: 201 Created
Output structure : object

Parameter name Type Description
token_id string Client's application token
Example of HTTP header before encoding

Warning: Do not use this HTTP header example before it is encoded. It is here just to inform you about the HTTP header content before encoding.

POST `<projectURL>`/customer-interface/v1.0/tokens
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic customer_interface:
Example of HTTP header after BASE 64 encoding

This encoded HTTP header example can be used as a request header

POST `<projectURL>`/customer-interface/v1.0/tokens
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
#customer_interface:
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNlOiA=
Example of request body
{
  "device": {
  "device_id" : "123456",
  "device_system" :  "OSX",
  "device_name" :  "Test device",
  "device_type" :  "iPhone"},
  "setup" : {"language_id" :  "en",
  "external_application_id": "86e05affc7a7abefcd513ab400",
  "allowed_gps" :  true,
  "allowed_notifications" :  false},
  "push_token" : "4f7f658bfa7a5959e093590"
}
Example of response body
{
    "data":{
        "token_id":"c5a67da2c3a874f7f658bfa7a5959e09359095c5da43c7a78e11e710eabce49418715a6a"
    }
}

Edit a push token

Update a push token and installation setup
[badge-grey PUT] /tokens/{token_id}

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes

Request

Parameter name Type Description Mandatory (Yes/No)
setup Setup Setup of the client's device Yes
push_token string Push notification token (Apple or Google) No

Response

Status code: 204 No Content
Output structure : object

Example Request

PUT https://<projectURL>/rest-api/customer-interface/v1.0/tokens/d9aacfc5eebfae1e9fdc7f20694c2ca105dff986f1b8176a6740c027db56a325913f
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic Y3VzdG9tZXJfaW50ZXJmYWNkN2RhZjgyYzBmNzVjMzYzYmU4OGUzNzQ3ZWIzY2FkOWYyZjVmZDVhZDExNjI4MWFkMTAxYWNhZGMzZGViYQ==

{
  "setup" : 
  {
  "language_id" :  "en",
  "allowed_gps" :  true,
  "allowed_notifications" :  false
  },
  "push_token" : "4f7f658bfa7a5959e093590"
}

Example Response

HTTP/1.1 204 No Content
Date: Fri, 11 Dec 2020 16:47:03 GMT
Content-Type: application/json; charset=utf-8

Login to the application

Login of a customer account to client's application
[badge-green POST] /tokens/{token_id}/actions/login

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes

Request

Parameter name Type Description Mandatory (Yes/No)
login_type string The unique id for the login type.
Possible values: card / email
Yes
login_value string Value of the login to Customer interface API Yes
password string Password of the customer Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
customer_id string The unique id for a logged in customer
Example of request body
{
  "login_type": "email",
  "login_value": "example@crmcarecloud.com",
  "password": "password_example"
}
Example of response body
{
    "data":{
        "customer_id":"09359095c5da43c7a78e11e710eabce49418715a6a"
    }
}

Logout from the application

Logout of a customer account to client's application
[badge-green POST] /tokens/{token_id}/actions/logout

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes
Response

Status code: 204 No Content

Login via social network

Login of a customer account to client's application via social network
[badge-green POST] /tokens/{token_id}/actions/social-network-login

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes

Request

Parameter name Type Description Mandatory (Yes/No)
social_network_credentials SocialNetworkCredentials Credentials of the specific social network Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
customer_id string The unique id for the logged in customer
Example of request body
{
  "social_network_id": "facebook",
  "social_network_token": "a78e11e774f7f10ea"
}
Example of response body
{
    "data":{
        "customer_id":"09359095c5da43c7a78e11e70eabce49418715a6a"
    }
}

Send email for set up of the new customer password

Send email, that contains link to set up a password
[badge-green POST] /tokens/{token_id}/actions/send-password-setup-email

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes

Request

Parameter name Type Description Mandatory (Yes/No)
email string Message with a setup password link will be delivered to this email address Yes

Response

Status code: 204 No Content

Example of request body
{
  "email": "happy_customer@carecloud.com"
}

Get authentication token

Returns authentication token for specific external application
[badge-blue GET] /tokens/{token_id}/actions/auth-token

Path parameters

Parameter name Type Description Mandatory (Yes/No)
token_id string Client's application token Yes

Query string

Parameter name Type Description Mandatory (Yes/No)
external_application_id string Id of external application. For id of external application, please contact your account manager or look to resource customer-external-applications Yes
token_type string Parameter set witch token type should be generated.
Possible values: 1- alphanumeric, 2- numeric Default value: 1
Yes

Response

Status code: 200 OK
Output structure : object

Parameter name Type Description
authentication_token string Authentication token for external application
token_request_id string The parameter specifies the request that caused the token to be created. If two customers generated an authentication token at the same time and in the same application, the token_request_id parameter represents additional verification to identify the correct token

Example of request

GET https://<projectURL>/rest-api/enterprise-interface/v1.0/tokens/744616b5c93fef9a55c1487586c4162c0210ea556c290b5dc684f589d584909faed8e2/actions/auth-token?external_application_id=1&token_type=1
Content-Type: application/json
Accept-Language: cs, en-gb;q=0.8
Authorization: Basic ZW50ZXJwcmlzZV9pbnRlcmZhY2U6ZDlmMGRiDcwZGMmM0OWE0ZjMxY2U4NTY2OGM1NzM1NGQ5YjUzODY5MmE5OTBjMjI1NDUwYzcyMw==

Example response

HTTP/1.1 200 OK
Date: Tue, 04 May 2021 09:37:14 GMT
Content-Type: application/json; charset=utf-8

{
  "data": {
    "authentication_token": "LQ55EH",
    "token_request_id": "76951b4a90626f3635990330ec487e32c539c74"
  }
}