Authenticating as a service account

Learn how to get authenticated in the Yandex Cloud CLI:

• On behalf of a service account using impersonation. Using impersonation is the recommended and most secure way to get authenticated in the Yandex Cloud CLI.
• On behalf of a service account using an authorized key. Using an authorized key allows you to continually get authenticated in the Yandex Cloud CLI with the same authorized key you generated. Using a long-lived key is less secure than using impersonation.
• 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.

Service accounts are different from user accounts or federated user accounts. You cannot use service accounts to log in to the management console, but you can use them to manage resources in Yandex Cloud.

Getting startedGetting started

1. Authenticate in the CLI as a user or a federated user.
2. If you do not have a service account yet, create one and configure access permissions for it.

Perform actions on behalf of a service account using impersonationPerform actions on behalf of a service account using impersonation

To perform an action on behalf of a service account:

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

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

   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. 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>
   

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 on behalf of a service account using an authorized keyGet authenticated on behalf of a service account using an authorized key

To authenticate as a service account:

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

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

   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>
   

   Result:

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

3. 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
      

4. 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-----
   

5. 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.

   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.

   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 VMAuthenticate as a service account from inside a VM

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. 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.

   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.

   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.

See alsoSee also

• Managing a CLI configuration.
• Creating a profile.
• Activating a profile.
• Managing profile parameters.
• Using Yandex Cloud from within a VM.