Authorization
Login and authorization flows
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.
To use the API you need to obtain the Refresh Token first.
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
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.
All query parameters except
state are required.Name | Description |
|---|---|
client_id | |
client_secret | |
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) |
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-stateAfter 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.To call any of the authenticated API v2 endpoints you need to obtain the Access Token first.
post
https://api.dotykacka.cz
/v2/signin/token
Get Access Token
In some special cases you may want to get an Access Token without specifying the cloud ID. Such token allows you only to Get list of clouds. Access to all other endpoints with
_cloudId in the URI will be denied.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.
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.
Last modified 3mo ago