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

Assigning roles to a service account

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

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.

To assign a role for a resource, you need the admin or service-name.admin role, where service-name is the name of the service to which the resource belongs.

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, click or in the top panel and 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 used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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> \
  --service-account-id <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.
  • --service-account-id: ID of the service account you are assigning the role to.

For example, to assign a service account the role for the 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 <service_account_name>

    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 role to the service account using its ID:

    yc resource-manager folder add-access-binding <folder_name_or_ID> \
  --role <role> \
  --service-account-id <service_account_ID>

    Where:

    • --role: ID of the role you need to assign.
    • --service-account-id: Service account ID. You can also use the --service-account-name parameter and specify the username instead of the ID.

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

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

  1. In the configuration file, describe the resources you want to create:

    Sample configuration file structure for assigning a role to a folder:

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

    • role: Role. 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 setting.

    • member: Subject getting the role. For a service account, specify serviceAccount:<service_account_ID>.

      Subject designations

      To indicate a subject, use a combination of its type and unique ID, i.e., <subject_type>:<ID>. How you can designate a subject:

      Subject type

      Subject designation

      userAccount

      userAccount:<user_ID>

      serviceAccount

      serviceAccount:<service_account_ID>

      federatedUser

      federatedUser:<user_ID>

      group

      group:<group_ID>

      system

      system:allAuthenticatedUsers

      (All authenticated users group)

      system:allUsers

      (All users group)

      system:group:organization:<organization_ID>:users

      (All users in organization X group)

      system:group:federation:<federation_ID>:users

      (All users in federation N group)

      system:group:userpool:<pool_ID>:users

      (All users in userpool P group)

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

  2. Create the resources:

    1. In the terminal, navigate to the configuration file directory.

    2. Make sure the configuration is correct using this command:

      terraform validate

      If the configuration is valid, you will get this message:

      Success! The configuration is valid.

    3. Run this command:

      terraform plan

      You will see a list of resources and their properties. No changes will be made at this step. Terraform will show any errors in the configuration.

    4. Apply the configuration changes:

      terraform apply

    5. Type yes and press Enter to confirm the changes.

    This will assign access permissions for the folder. You can check the role assignment 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 for authentication in the Yandex Cloud API.

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

    export FOLDER_ID=<folder_ID>
export IAM_TOKEN=<IAM_token>
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. Specify ADD in the action property:

    {
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "<role>",
      "subject": {
        "id": "<service_account_ID>",
        "type": "serviceAccount"
      }
    }
  }]
}

    Where:

    • roleId: Role.

    • subject: Subject getting the role.

      Subject designations

      To indicate a subject, use a combination of its type and unique ID in the subject.type and subject.id fields of the request. Possible combinations:

      subject.type

      subject.id

      userAccount

      <user_ID>

      serviceAccount

      <service_account_ID>

      federatedUser

      <user_ID>

      group

      <group_ID>

      system

      allAuthenticatedUsers

      (All authenticated users group)

      allUsers

      (All users group)

      group:organization:<organization_ID>:users

      (All users in organization X group)

      group:federation:<federation_ID>:users

      (All users in federation N group)

      group:userpool:<pool_ID>:users

      (All users in userpool P group)

  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 Identity Hub 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 roles.

    If the service account is not on the list, click Assign roles 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 used by default is the one specified when creating the CLI profile. To change the default folder, use the yc config set folder-id <folder_ID> command. You can also specify a different folder for any command using --folder-name or --folder-id. If you access a resource by its name, the search will be limited to the default folder. If you access a resource by its ID, the search will be global, i.e., through all folders based on access permissions.

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> \
  --service-account-id <service_account_ID>

Where:

  • <organization_name_or_ID>: Technical name or ID of the organization.
  • --role: Role ID, e.g., viewer.
  • --service-account-id: ID of the service account you are assigning the role 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 \
  --service-account-id aje6o61dvog2********

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

To manage infrastructure using Terraform under a service account or user accounts (a Yandex account, a federated account, or a local user), authenticate using the appropriate method.

  1. In the configuration file, describe the resources you want to create:

    Here is an example of the configuration file structure:

    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 setting.
    • role: Role. 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_organizationmanager_organization_iam_binding resource. This is a required setting.
    • members: Designations of subjects getting the role. This is a required setting.

    For more on the properties of the yandex_organizationmanager_organization_iam_binding resource, see this provider guide.

  2. Make sure the settings are correct.

    1. In the command line, navigate to the directory that contains the current Terraform configuration files defining the infrastructure.

    2. Run this command:

      terraform validate

      Terraform will show any errors found in your configuration files.

  3. Assign the role.

    1. Run this command to view the planned changes:

      terraform plan

      If you described the configuration correctly, the terminal will display a list of the resources to update and their parameters. This is a verification step that does not apply changes to your resources.

    2. If everything looks correct, apply the changes:

      1. Run this command:

        terraform apply

      2. Confirm updating the resources.

      3. Wait for the operation to complete.

    This will assign access permissions for the organization. You can check the role assignment using the management console or this CLI command:

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

To assign a service account a role for an organization, use the updateAccessBindings REST API method for the Organization resource or the OrganizationService/UpdateAccessBindings gRPC API call:

  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 for authentication in the Yandex Cloud API.

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

    export FOLDER_ID=<folder_ID>
export IAM_TOKEN=<IAM_token>
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=<IAM_token>
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. Specify ADD in the action property:

    body.json:

    {
  "accessBindingDeltas": [{
    "action": "ADD",
    "accessBinding": {
      "roleId": "<role>",
      "subject": {
        "id": "<service_account_ID>",
        "type": "serviceAccount"
      }
    }
  }]
}

    Where:

    • roleId: Role.

    • subject: Subject getting the role.

      Subject designations

      To indicate a subject, use a combination of its type and unique ID in the subject.type and subject.id fields of the request. Possible combinations:

      subject.type

      subject.id

      userAccount

      <user_ID>

      serviceAccount

      <service_account_ID>

      federatedUser

      <user_ID>

      group

      <group_ID>

      system

      allAuthenticatedUsers

      (All authenticated users group)

      allUsers

      (All users group)

      group:organization:<organization_ID>:users

      (All users in organization X group)

      group:federation:<federation_ID>:users

      (All users in federation N group)

      group:userpool:<pool_ID>:users

      (All users in userpool P group)

  7. Assign the role to the service account:

    export ORGANIZATION_ID=<organization_ID>
export IAM_TOKEN=<IAM_token>
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