Authorization

Login and authorization flows

Client Application

To access the API v2 you need to create Client Application and obtain Client Application credentials. Please follow the Getting started guide.

The Client Application is used to the differentiation of API usages and allows you to offer the same integration for multiple independent customers.

The Client ID and Client Secret is used only to connect your Application with the Cloud of Dotypos User. Provided Client ID and Client Secret should be kept private and used only for the connection of your Application.

TIP: For your first steps you can use our Postman collection.

Connecting Client Application (Refresh Token)

To use the API you need to obtain the Refresh Token first.

Flow description

To retrieve the Refresh Token, you need to redirect the user from your application to the connector web page where the user has to allow access for your application (see the screenshot below). After granting the access, the user will be redirected to the webhook redirect_uri with query parameters which contain the Refresh Token.

This Refresh Token should be stored safely in your application and used for retrieving Access Token required for all authenticated API endpoints.

Connector web page

Connector web page URL

To obtain the Refresh Token you have to redirect the user to the following web page where the user grants access to your application:

https://admin.dotykacka.cz/client/connect (+ query parameters, see below)

The above URL is not a REST API endpoint. It has to be opened using a web browser to allow users to interact with the page. Your application can start a browser directed to the URL including the query parameters.

List of query parameters

All query parameters except state are required.

Name	Description
client_id	Client ID (received after registration)
client_secret	Client Secret (received after registration)
scope	Scope of requested access * is the only supported value now
redirect_uri	Indicates the URI to return the user to after registration is complete
state (optional)	A value used to maintain state between the request and callback. The parameter is used to protect against Cross-Site Request forgery (CSRF)

Connector web page URL format

This is the full web URL to redirect users to for granting access to your application and obtaining the Refresh Token:

https://admin.dotykacka.cz/client/connect?client_id={client_id}&client_secret={client_secret}&scope=*&redirect_uri={webhook}&state=my-state

Query parameters provided to the redirect_uri webhook

After granting access the user will be redirected to the provided redirect_uri with the following query parameters:

Name	Description
token	Refresh Token
cloudid	Selected Cloud ID
state	CSRF parameter provided in redirect request (provided only if presented in redirect request)

If you are using the first version (deprecated now) of the API you need to retrieve new Refresh Token. API v2 Refresh Token is not compatible with API v1 token format.

TIP If your application is internal and single purpose only you can use a dummy url (e.g. https://dotykacka.cz) and copy the token value from the url after the redirection. Don't use this for external client implementations.

Signing into API v2 (Access Token)

To call any of the authenticated API v2 endpoints you need to obtain the Access Token first.

Get Access Token

POST https://api.dotykacka.cz/v2/signin/token

Returns Access Token for a provided Refresh Token. Default validity of Access Token is one hour (not guaranteed). The request body must be in the JSON format (form-data is not accepted and returns error).

Headers

Name	Type	Description
Authorization*	string	User $refreshToken

Request Body

Name	Type	Description
_cloudId	string	Cloud ID, should be specified to get access to the most endpoints

201 Access token claims

{
    "accessToken": "eyJ0.eyJ1.eyJ2..."
}

401

{}

Access Token without Cloud ID (special case)

In some special cases you may want to get an Access Token without specifying the cloud ID. To do this, send an empty JSON object in the request body. Such token allows you only to Get list of clouds. Access to all other endpoints with _cloudId in the URI will be denied.

JSON body

{
}

Access Token with Cloud ID (standard use-case)

To get access to all endpoints (standard use-case) you need to retrieve the Access Token for the specific cloud. This is done by specifying the cloud ID in the request JSON body.

JSON body

{
    "_cloudId": {cloudId}
}

The returned Access Token will allow you to access the specified cloud only. To obtain access into another cloud you need to call the Get Access Token again with a new cloud ID in the JSON body and use the new Access Token to call endpoints for this cloud.

Access Token usage

For each API v2 authenticated request, you need to include the Access Token in the HTTP request headers:

Authorization: Bearer {AccessToken}

This is described with every endpoint method in the documentation.

Please see the Breaking changes page for more info on the planned changes in validation.