Discuss with expertTry it for free
© 2026 Direct Cursus Technology L.L.C.

Authenticating in the Yandex Cloud CLI as a service account

Written by
Improved by
Updated at August 19, 2026
View in Markdown

Note

When performing actions on behalf of a service account, ensure that it has the required roles assigned to it.

Warning

Creating service accounts and their keys may be prohibited by access policies at the folder, cloud, or organization level.

Learn how to get authenticated in the Yandex Cloud CLI:

  • As a service account using impersonation

    Using impersonation is the recommended and most secure way to get authenticated in the Yandex Cloud CLI.

    This method is not suitable for servers without a GUI because the user first needs to get authenticated to the CLI with a Yandex account, federated account, or local user account through the browser.

  • As a service account using an authorized key

    You can create an authorized key with an unlimited lifetime and continuously use it to authenticate in the Yandex Cloud CLI. Using a long-lived key is less secure than using impersonation.

    To get an authorized key, you must initially authenticate in the CLI using a Yandex account, federated account, or local user account from a device that has a browser and GUI. Further CLI operations can be performed on a server without a GUI.

  • As a service account from inside a VM

    Using a service account attached to the Yandex Compute Cloud VM is the recommended method of authentication in the Yandex Cloud CLI when using a VM.

    This method does not require initial CLI authentication with a Yandex account, federated account, or local user account, nor does it require the server to have a browser or GUI.

Service accounts are different from Yandex user accounts, federated user accounts, or local user accounts. You cannot use a service account to log in to the management console but you can use them to manage Yandex Cloud resources via the CLI, Terraform, and API.

Getting started

If you do not have a service account yet, create one and configure access permissions for it.

Tip

If your organization uses a proxy server to access Yandex Cloud, configure the CLI connection to the proxy server before running the yc init command.

Perform actions as a service account using impersonation

Using impersonation is the recommended and most secure way to get authenticated in the Yandex Cloud CLI.

This method is not suitable for servers without a GUI because the user first needs to get authenticated to the CLI with a Yandex account, federated account, or local user account through the browser.

Note

To use impersonation, the user must have the iam.serviceAccounts.tokenCreator role for the service account.

To perform an action on behalf of a service account:

  1. Install the CLI.

  2. Authenticate in the CLI as a Yandex user, federated user, or local user.

  3. Get a list of service accounts that exist in your cloud:

    yc iam service-account --folder-id <folder_ID> list

    Where --folder-id is the folder ID.

    Result:

    +----------------------+------------+--------+---------------------+-----------------------+
|          ID          |    NAME    | LABELS |     CREATED AT      | LAST AUTHENTICATED AT |
+----------------------+------------+--------+---------------------+-----------------------+
| ajeg2b2et02f******** | my-robot   |        | 2024-09-08 18:59:45 | 2025-08-21 06:40:00   |
| ajegtlf2q28a******** | default-sa |        | 2023-06-27 16:18:18 | 2025-08-21 06:30:00   |
+----------------------+------------+--------+---------------------+-----------------------+

  4. When running Yandex Cloud CLI commands, use impersonation of your service account by specifying its ID in the --impersonate-service-account-id parameter.

    For example, to create a bucket named my-sample-bucket in the default folder on behalf of a service account, run this command:

    yc storage bucket create \
  --name my-sample-bucket \
  --impersonate-service-account-id <service_account_ID>

    Where --impersonate-service-account-id is the service account ID you got earlier.

Some commands require that you specify unique IDs for your cloud and folder. You can run such commands with the --cloud-id and --folder-id parameters.

Get authenticated as a service account using an authorized key

You can create an authorized key with an unlimited lifetime and continuously use it to authenticate in the Yandex Cloud CLI. Using a long-lived key is less secure than using impersonation.

To get an authorized key, you must initially authenticate in the CLI using a Yandex account, federated account, or local user account from a device that has a browser and GUI. Further CLI operations can be performed on a server without a GUI.

  1. Install the CLI.

  2. Authenticate in the CLI as a Yandex user, federated user, or local user.

    Warning

    To get authenticated in the CLI with a Yandex account, federated account, or local user account, you need a browser and a GUI.

    To use a service account on a server without a GUI, first complete the preparation steps on a device with a GUI and a browser.

  3. Create an authorized key and use it to get authenticated in the CLI:

    1. Get a list of service accounts that exist in your cloud:

      yc iam service-account --folder-id <folder_ID> list

      Where --folder-id is the folder ID.

      Result:

      +----------------------+------------+--------+---------------------+-----------------------+
|          ID          |    NAME    | LABELS |     CREATED AT      | LAST AUTHENTICATED AT |
+----------------------+------------+--------+---------------------+-----------------------+
| ajeg2b2et02f******** | my-robot   |        | 2024-09-08 18:59:45 | 2025-08-21 06:40:00   |
| ajegtlf2q28a******** | default-sa |        | 2023-06-27 16:18:18 | 2025-08-21 06:30:00   |
+----------------------+------------+--------+---------------------+-----------------------+

    2. Create an authorized key for the service account and save it to a file named key.json:

      yc iam key create \
  --service-account-name default-sa \
  --output key.json \
  --folder-id <folder_ID>

      Where:

      • --service-account-name: Name of the service account you got earlier.
      • --output: Name of the file to save the authorized key to.
      • --folder-id: ID of the folder with the service account.

      Result:

      id: aje83v701b1u********
service_account_id: aje3932acd0c********
created_at: "2019-08-26T12:31:25Z"
key_algorithm: RSA_2048

    3. If you created an authorized key on your local machine and want to use it to authenticate in the CLI on a VM, copy it over SCP beforehand.

    4. Add the service account authorized key to the CLI profile.

      1. Create a new CLI profile:

        yc config profile create sa-profile

      2. Add an authorized key:

        yc config set service-account-key key.json

    5. Make sure the parameters for the service account are added correctly:

      yc config list

      Result:

      service-account-key:
  id: aje83v701b1u********
  service_account_id: aje3932acd0c********
  created_at: "2019-08-26T12:31:25Z"
  key_algorithm: RSA_2048
  public_key: |
    -----BEGIN PUBLIC KEY-----
    MIIBIjANBg...
    -----END PUBLIC KEY-----
  private_key: |
    -----BEGIN PRIVATE KEY-----
    MIIEvwIBAD...
    -----END PRIVATE KEY-----

    6. Configure your profile to run commands.

      Some commands require that you specify unique IDs for your cloud and folder. You can specify their details in the profile or use a specific flag for these commands.

      1. Specify the cloud in your profile:

        yc config set cloud-id <cloud_ID>

        You can also use the --cloud-id parameter to run commands.

        For more information, see Getting a cloud ID.

      2. Specify a folder in the profile:

        yc config set folder-id <folder_ID>

        You can also use the --folder-id parameter to run commands.

        For more information, see Getting the folder ID.

      All operations in this profile will be performed on behalf of the linked service account. You can change the profile parameters or switch to another profile.

Authenticate as a service account from inside a VM

Using a service account attached to the Yandex Compute Cloud VM is the recommended method of authentication in the Yandex Cloud CLI when using a VM.

This method does not require initial CLI authentication with a Yandex account, federated account, or local user account, nor does it require the server to have a browser or GUI.

The authentication process from inside a VM is simplified for a service account:

  1. Link your service account to a VM.

  2. Authenticate from inside a VM:

    1. Connect to the VM over SSH.

    2. Install the CLI.

    3. Create a new profile:

      yc config profile create my-robot-profile

  3. Configure your profile to run commands.

    Some commands require that you specify unique IDs for your cloud and folder. You can specify their details in the profile or use a specific flag for these commands.

    1. Specify the cloud in your profile:

      yc config set cloud-id <cloud_ID>

      You can also use the --cloud-id parameter to run commands.

      For more information, see Getting a cloud ID.

    2. Specify a folder in the profile:

      yc config set folder-id <folder_ID>

      You can also use the --folder-id parameter to run commands.

      For more information, see Getting the folder ID.

    All operations in this profile will be performed on behalf of the linked service account. You can change the profile parameters or switch to another profile.

Read more about working with Yandex Cloud from a VM in Using Yandex Cloud from within a VM.

Useful links

Previous
Yandex account
Next
Federated user