Authorization
Users authorize in RouteQ using Yandex ID. We recommend observing all the account protection rules for your RouteQ account.
To access RouteQ, your account or Yandex ID must be linked to a specific company ID. An account can be linked to only one company, but a company can contain multiple accounts. If the company already has an ID, then its administrator can add new users. If you create a new company, then the account that the user was authorized under when creating the company will be added as the administrator.
Note
When working with accounts:
-
To register a company, use a separate email address that is not used for personal email. This ensures the company will maintain its access if, for example, an employee is dismissed. For more information, see Before you register.
-
Create separate accounts for different users so that employees don't lose access if anyone changes the account password.
The authorization method depends on which RouteQ features you plan to use:
-
To plan routes only in the interface, all you need are the company ID and the account linked to the company. For more information, see Registration.
-
To use the Planning API, you need an API key.
-
To use the Track & Trace API and some features of the Planning API (such as geofences from the Master data), you need an OAuth token.
Relationship of objects
API key
Overview
Route planning API uses an access key for authentication. Pass it in the request using the HTTP POST method as an apikey parameter value.
Note
The use of the key is chargeable, make sure that only authorized persons know it.
There are two ways to get a key:
-
Using the Yandex Developer Dashboard, a special portal that allows you to generate keys for the APIs of various Yandex services. The key you obtain this way has a limited validity period and some other characteristics. After receiving the key to access Routing Workspace, you need to contact your manager.
-
In the web interface of the service (Company section). If you already registered in RouteQ, a key was created automatically and you don't need to get it in Yandex Developer Dashboard. After you pay for the service, the key's validity period is extended.
Getting a key in the Yandex Developer Dashboard
-
Log in to Yandex with the username you are going to use with the API.
-
Go to the Yandex Developer Dashboard and click Connect APIs.
-
Select RouteQ: Planning and Track & Trace and click Continue.
-
Fill out the form and click Submit.
-
In the window that opens, click Go to API.
-
The page of your keys for the RouteQ API opens. It usually takes up to 15 minutes to activate a new key, after which you can use it.
Using an API key
Example of a request with authorization via an API key:
curl -H "Content-Type: application/json" -X POST -d <request_body> https://courier.yandex.ru/vrs/api/v1/add/mvrp?apikey=<your_API_key>
In the request body, replace <your_API_key> with the obtained API key.
For more information about managing API keys in Yandex Developer Dashboard, see the documentation.
OAuth token
Overview
To work with Planning and some Track & Trace features (such as geofences from the Master data), you can use an OAuth token. OAuth token requirements:
- The token must be created for a user who's an administrator in the company.
- The token mustn't be revoked. For more information, see Token lifetime.
For more information about getting a token, see the service documentation.
Using an OAuth token
Example of a request with authorization via an OAuth token:
curl -H "Content-Type: application/json" -H "Authorization: OAuth <your-token>" -X POST -d <request body> https://courier.yandex.ru/api/v1/vrs/add/mvrp
In the Authorization: OAuth <your-token> header, change <your-token> to the OAuth token that you received for Track & Trace.
Warning
The path in the authorization request (with an OAuth token) is different from the path indicated in the specifications (with an API key).
If you use token-based authorization for planning, the task in the solution history will be displayed with the email of the user who was issued the token. To allocate tasks between regions, depots, or distribution centers, you can use different tokens issued to different email addresses of your administrators. For example, if you work in two regions, you can create two email addresses: region_1@example.com and region_2@example.com.