Contact UsGet started
© 2025 Direct Cursus Technology L.L.C.

Assigning roles to a service account

Written by
Updated at May 5, 2025

This section describes how to assign a role to a service account for a resource. To learn how to assign a role for a service account as a resource to another user, see Setting up service account access permissions.

You can assign roles to a service account for any resources in any cloud if these resources belong to the same organization as the service account. You can also assign roles to a service account for the organization.

Assigning a role for a resource

Child resources inherit access permissions from their parent resources. For example, if a service account gets a role for a cloud, it will also get the required permissions for all resources across the cloud's folders.

Learn which resources you can assign a role for.

To assign a role for a resource:

You assign roles to a service account the same way as to a user account.

To assign a service account a role for a cloud or folder:

  1. In the management console, select the cloud or folder.
  2. Navigate to the Access bindings tab.
  3. Click Configure access.
  4. In the window that opens, select Service accounts.
  5. Select the service account from the list or use the search bar.
  6. Click Add role and select the role from the list or use the search bar.
  7. Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To assign a service account a role for a cloud or folder, run this command:

yc resource-manager <resource_category> add-access-binding <resource_name_or_ID> \
  --role <role_ID> \
  --subject serviceAccount:<service_account_ID>

Where:

  • <resource_category>: cloud to assign a role for a cloud or folder to assign a role for a folder.
  • <resource_name_or_ID>: Name or ID of the resource to assign a role for.
  • --role: Role ID, e.g., viewer.
  • --subject serviceAccount: ID of the service account the role is assigned to.

For example, to assign a service account the viewer role for the folder named my-folder:

  1. Select the role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

  2. Find out the service account ID by its name:

    yc iam service-account get my-robot

    Result:

    id: aje6o61dvog2********
folder_id: b1gvmob95yys********
created_at: "2018-10-15T18:01:25Z"
name: my-robot

    If you don't know the name of the service account, get a list of service accounts with their IDs:

    yc iam service-account list

    Result:

    +----------------------+------------------+-----------------+
|          ID          |       NAME       |   DESCRIPTION   |
+----------------------+------------------+-----------------+
| aje6o61dvog2******** | my-robot         | my description  |
+----------------------+------------------+-----------------+

  3. Assign the viewer role to the my-robot service account using its ID:

    yc resource-manager folder add-access-binding my-folder \
  --role viewer \
  --subject serviceAccount:aje6o61dvog2********

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

  1. In the configuration file, define the parameters of the resources you want to create:

    Here is the configuration file example:

    resource "yandex_resourcemanager_folder_iam_member" "admin-account-iam" {
  folder_id   = "<folder_ID>"
  role        = "<role>"
  member      = "serviceAccount:<service_account_ID>"
}

    Where:

    • folder_id: Folder ID. This is a required parameter.
    • role: Role to assign. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference. This is a required parameter.
    • member: ID of the service account the role is assigned to. Use this format: serviceAccount:<service_account_ID>. This is a required parameter.

    For more information about the resources you can create with Terraform, see this provider reference.

  2. Make sure the configuration files are correct.

    1. In the command line, go to the directory where you created the configuration file.

    2. Run a check using this command:

      terraform plan

    If the configuration is correct, the terminal will display a list of the resources being created and their parameters. If the configuration contains any errors, Terraform will point them out.

  3. Deploy the cloud resources.

    1. If the configuration does not contain any errors, run this command:

      terraform apply

    2. Confirm creating the resources: type yes in the terminal and press Enter.

    This will create all the resources you need in the specified folder. You can check the new resource using the management console or this CLI command:

    yc resource-manager folder list-access-bindings <folder_name_or_ID>

To assign the service account a role for a cloud or folder, use the updateAccessBindings REST API method for the Cloud or Folder resource:

  1. Select the role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

  2. Get the ID of the service accounts folder.

  3. Get an IAM token required for authorization in the Yandex Cloud API.

  4. Get a list of folder service accounts to find out their IDs:

    export FOLDER_ID=b1gvmob95yys********
export IAM_TOKEN=CggaATEVAgA...
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"

    Result:

    {
 "serviceAccounts": [
  {
   "id": "ajebqtreob2d********",
   "folderId": "b1gvmob95yys********",
   "createdAt": "2018-10-18T13:42:40Z",
   "name": "my-robot",
   "description": "my description"
  }
 ]
}

  5. Create the request body, e.g., in the body.json file. Set the action property to ADD and roleId to the appropriate role, such as editor, and specify the serviceAccount type and service account ID in the subject property:

    body.json:

    {
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "editor",
      "subject": {
        "id": "ajebqtreob2d********",
        "type": "serviceAccount"
      }
    }
  }]
}

  6. Assign a role to a service account. For example, for a folder with the b1gvmob95yys******** ID:

    export FOLDER_ID=b1gvmob95yys********
export IAM_TOKEN=CggaAT********
curl \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  "https://resource-manager.api.cloud.yandex.net/resource-manager/v1/folders/${FOLDER_ID}:updateAccessBindings"

Assigning a role for an organization

Access permissions are inherited from an organization by all resources created in the organization. For example, if a service account gets a role for an organization, it will also get the required permissions for all resources across the organization's clouds.

To grant a service account permissions to access an organization, you need the organization-manager.admin role or higher.

  1. Log in to Yandex Cloud Organization using an administrator or organization owner account.

  2. In the left-hand panel, select Access bindings.

  3. In the Account type filter, select Service accounts.

  4. If the service account you need already has at least one role assigned, click in the row with that service account and select Assign bindings.

    If the service account is not on the list, click Assign bindings in the top-right corner. In the window that opens, go to Service accounts and select the account from the list or use the search bar to locate it.

  5. Click Add role and select the role to assign to the service account. You can assign multiple roles.

    You can find the description of the available roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

  6. Click Save.

If you do not have the Yandex Cloud CLI yet, install and initialize it.

The folder specified when creating the CLI profile is used by default. To change the default folder, use the yc config set folder-id <folder_ID> command. You can specify a different folder using the --folder-name or --folder-id parameter.

To assign a service account a role for an organization, run this command:

yc organization-manager organization add-access-binding <organization_name_or_ID> \
  --role <role_ID> \
  --subject serviceAccount:<service_account_ID>

Where:

  • <organization_name_or_ID>: Technical name or ID of the organization.
  • --role: Role ID, e.g., viewer.
  • --subject serviceAccount: ID of the service account the role is assigned to.

For example, to assign a service account the viewer role for the MyOrg organization:

  1. Select the role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

  2. Get a list of available organizations to find out their IDs and technical names:

    yc organization-manager organization list

    Result:

    +---------------------------------+---------------------------------+----------------------+
|               ID                |              NAME               |        TITLE         |
+---------------------------------+---------------------------------+----------------------+
| bpf1smsil5q0********            | hdt5j5uw********                | MyOrg                |
+---------------------------------+---------------------------------+----------------------+

    The organization's technical name is in the NAME column and its ID, in the ID column.

  3. Find out the service account ID by its name:

    yc iam service-account get my-robot

    Result:

    id: aje6o61dvog2********
folder_id: b1gvmob95yys********
created_at: "2018-10-15T18:01:25Z"
name: my-robot

    If you do not know the name of the service account, get a complete list of service accounts with their IDs:

    yc iam service-account list

    Result:

    +----------------------+------------------+-----------------+
|          ID          |       NAME       |   DESCRIPTION   |
+----------------------+------------------+-----------------+
| aje6o61dvog2******** | my-robot         | my description  |
+----------------------+------------------+-----------------+

  4. Assign the my-robot service account the viewer role for the organization with the bpf1smsil5q0******** ID:

    yc organization-manager organization add-access-binding bpf1smsil5q0******** \
  --role viewer \
  --subject serviceAccount:aje6o61dvog2********

If you do not have Terraform yet, install it and configure its Yandex Cloud provider.

  1. In the configuration file, define the parameters of the resources you want to create:

    Here is the configuration file example:

    resource "yandex_organizationmanager_organization_iam_binding" "editor" {
  organization_id   = "<organization_ID>"
  role              = "<role>"
  members           = [
                        "serviceAccount:<service_account_ID>",
                      ]
}

    Where:

    • organization_id: Organization ID. This is a required parameter.
    • role: Role to assign. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference. For each role, you can only use one yandex_organization manager_organization_iam_binding resource. This is a required parameter.
    • members: ID of the service account the role is assigned to. Use this format: serviceAccount:<service_account_ID>. This is a required parameter.

    For more information about the resources you can create with Terraform, see this provider reference.

  2. Make sure the configuration files are correct.

    1. In the command line, go to the directory where you created the configuration file.

    2. Run a check using this command:

      terraform plan

    If the configuration is described correctly, the terminal will display a list of the assigned roles. If the configuration contains any errors, Terraform will point them out.

  3. Deploy the cloud resources.

    1. If the configuration does not contain any errors, run this command:

      terraform apply

    2. Confirm creating the resources: type yes in the terminal and press Enter.

    This will create the required resources in the specified organization. You can check the new resource using the management console or this CLI command:

    yc organization-manager organization list-access-bindings <organization_name_or_ID>

To assign the service account a role for the organization, use the updateAccessBindings REST API method for the Organization resource:

  1. Select the role to assign to the service account. You can find the description of the roles in the Yandex Identity and Access Management documentation in the Yandex Cloud role reference.

  2. Get the ID of the service accounts folder.

  3. Get an IAM token required for authorization in the Yandex Cloud API.

  4. Get a list of folder service accounts to find out their IDs:

    export FOLDER_ID=b1gvmob95yys********
export IAM_TOKEN=CggaATEVAgA...
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  "https://iam.api.cloud.yandex.net/iam/v1/serviceAccounts?folderId=${FOLDER_ID}"

    Result:

    {
 "serviceAccounts": [
  {
   "id": "ajebqtreob2d********",
   "folderId": "b1gvmob95yys********",
   "createdAt": "2018-10-18T13:42:40Z",
   "name": "my-robot",
   "description": "my description"
  }
 ]
}

  5. Get a list of organizations to find out their IDs:

    export IAM_TOKEN=CggaATEVAgA... 
curl \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --request GET \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/organizations"

    Result:

    {
 "organizations": [
  {
   "id": "bpfaidqca8vd********",
   "createdAt": "2023-04-07T08:11:54.313033Z",
   "name": "xvdq9q22********",
   "title": "MyOrg"
  }
 ]
}

  6. Create the request body, e.g., in the body.json file. Set the action property to ADD and roleId to the appropriate role, such as viewer, and specify the serviceAccount type and service account ID in the subject property:

    body.json:

    {
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "viewer",
      "subject": {
        "id": "ajebqtreob2d********",
        "type": "serviceAccount"
      }
    }
  }]
}

  7. Assign a role to a service account. For example, assign it for the organization with the bpfaidqca8vd******** ID:

    export ORGANIZATION_ID=bpfaidqca8vd********
export IAM_TOKEN=CggaATEVAgA...
curl \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer ${IAM_TOKEN}" \
  --data '@body.json' \
  --request POST \
  "https://organization-manager.api.cloud.yandex.net/organization-manager/v1/organizations/${ORGANIZATION_ID}:updateAccessBindings"

What's next

Previous
Updating a service account
Next
Setting up service account access permissions