Authenticate¶
ycli needs two values, read from the environment or from a .env file in the working directory:
YANDEX_ID_OAUTH_TOKEN=... # a Yandex OAuth token with Tracker, Wiki and Forms access
YANDEX_ID_ORGANIZATION_ID=... # your Yandex 360 organization id
ycli sends the organization id as the X-Org-Id header to every service.
Get a token with ycli auth login¶
Yandex issues OAuth tokens only through a registered application.
- Register an app at oauth.yandex.ru and grant it the
Tracker, Wiki and Forms permissions, read and write. The read permissions alone are
enough only for
ycli mcp start --read-only. -
Put its ClientID, and the Client secret if you want the headless flow, into
.env:YANDEX_OAUTH_CLIENT_ID=... YANDEX_OAUTH_CLIENT_SECRET=... # optional: enables the device flow -
Run
ycli auth login. It gets a token, detects your organization and writes both into.env:- with a client id and a secret it uses the device flow: it prints a code and a
https://ya.ru/devicelink, you approve there, and it captures the token. This works over SSH; - with only a client id, or with
--implicit, it uses the browser flow: it opens the Yandex authorization page, you approve and paste the token it shows back.
- with a client id and a secret it uses the device flow: it prints a code and a
Check the credentials¶
ycli auth status # whose token, which organization, which services accept it
ycli tracker auth status # one service only (also wiki, forms)
ycli doctor # every check in order, with what to fix for each one that fails
ycli doctor also says where each credential is set (the environment or the .env file, never its value) which extras are installed and whether a newer release is out; add -o json for an agent. All three exit non-zero when a service rejects the token. The organization's name needs the optional
directory:read_organization scope; without it you get the id and a note.
Use an IAM token¶
An account that cannot get an OAuth token (a federated one, for example) can use a ready IAM token instead:
export YANDEX_CLOUD_IAM_TOKEN="$(yc iam create-token)" # in place of YANDEX_ID_OAUTH_TOKEN
export YANDEX_ID_ORGANIZATION_ID=... # the same organization id
ycli doctor
It is sent as Authorization: Bearer and works for Tracker, Wiki and Forms. It lives up to 12 hours: when a call starts answering 401, issue a new one. Set one token, not both: with both, ycli stops with exit code 2 and names them. ycli auth status cannot name the owner or the organization for an IAM token (Yandex ID and API 360 take an OAuth token only); the service checks still run.
Keep several organizations¶
A profile is a saved pair of a token and an organization under a name. Save one per organization, then name the one a command should use:
ycli auth login --profile work # sign in and save the result as "work"
ycli auth login --profile client
ycli --profile client tracker me get # one command as "client"
export YCLI_PROFILE=work # every command of this shell as "work"
ycli auth profiles # the saved profiles, without their tokens
Once a profile is named, by --profile or by YCLI_PROFILE, it is the only source of the token and the organization: YANDEX_ID_OAUTH_TOKEN, YANDEX_ID_ORGANIZATION_ID and .env are not read for them, so an exported token cannot send a command to another organization. The option wins over the variable. With no profile named, nothing changes. Nothing remembers a "current" profile between commands.
A profile is one file, <name>.env, with the same variables as .env, in the profiles directory of your user configuration (ycli doctor prints the path; on Linux it is ~/.config/ycli/profiles). ycli auth login creates the file readable by you alone. Copy an existing .env there to make a profile by hand, and delete the file to remove one. A name has lowercase letters, digits, - and _. An unknown name, or a file without a token or an organization, stops the command with exit code 2.
The MCP server takes the same option over stdio: ycli mcp start --profile work.
Do it by hand¶
Device flow:
# 1. start the flow: returns a user_code and a verification_url
curl -s -X POST https://oauth.yandex.ru/device/code -d "client_id=$YANDEX_OAUTH_CLIENT_ID"
# 2. open https://ya.ru/device, enter the user_code, approve
# 3. exchange the device_code for the token
curl -s -X POST https://oauth.yandex.ru/token \
-d grant_type=device_code -d "code=<device_code>" \
-d "client_id=$YANDEX_OAUTH_CLIENT_ID" -d "client_secret=$YANDEX_OAUTH_CLIENT_SECRET"
Browser flow: open https://oauth.yandex.ru/authorize?response_type=token&client_id=<ClientID>
in a signed-in browser, approve, and copy the token from the page.
Organization id: tracker.yandex.ru/admin/orgs, your organization, the identifier field.
Yandex documentation¶
| Step | Yandex docs |
|---|---|
| Register the OAuth app | Registering an app |
| Device flow | Entering the code on the authorization page |
| Browser flow | Obtain a token manually |
| Token and organization header per service | Tracker · Wiki · Forms API access |