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 application endpoint you need to obtain Refresh Token first.

To retrieve the Refresh Token, you need to redirect user from your application to the connector page. After the successful connection user will be redirected to provided redirect_uri with query parameter token.

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

Redirect request url

List of query parameters

All query parameters except state are required.




Client ID (received after registration)


Client Secret (received after registration)


Scope of requested access

* is the only supported value now


Indicates the URI to return the user to after registration is complete



A value used to maintain state between the request and callback. The parameter is used to protect against Cross-Site Request forgery (CSRF)

Redirect url query parameters

User will be redirected to provided redirect_url with extra query parameters:




Refresh Token


Selected Cloud ID


CSRF parameter provided in redirect request

(provided only if presented in redirect request)

If you are using first version of 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 you can use dummy url (e.g. and copy token from url. Don't use this for external client implementations.

Get Access Token
Returns Access token for provided Refresh token. Default validity of Access token is 1 hour (not guaranted).
User $refreshToken
Body Parameters
Cloud ID, required for most of methods
201: Created
Access token claims
"accessToken": "eyJ0.eyJ1.eyJ2..."
401: Unauthorized

Access Token without Cloud ID

The access token obtained without specifying the cloud ID allows you only to Get list of clouds. Access to all other endpoints will be denied.

Access Token with Cloud ID

To get access to all endpoints you need to retrieve the Access Token for the specific cloud. This is done by specifying the cloud ID in the request body.

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.

Access Token usage

For every authenticated request, you need to include the Access Token in the Authorization headerAuthorization: Bearer accessToken . This is described with every method in the API Reference section of the documentation.