This page explains how to list and edit service accounts using the
Identity and Access Management (IAM) API, the Google Cloud console, and the gcloud
command-
line tool.
Before you begin
Enable the IAM API.
Understand IAM service accounts
Required roles
To get the permissions that you need to manage service accounts, ask your administrator to grant you the following IAM roles on the project:
-
To view service accounts:
View Service Accounts (
roles/iam.serviceAccountViewer
) -
To edit service accounts:
Service Account Admin (
roles/iam.serviceAccountAdmin
)
For more information about granting roles, see Manage access.
You might also be able to get the required permissions through custom roles or other predefined roles.
To learn more about these roles, see Service Accounts roles.
IAM basic roles also contain permissions to manage service accounts. You should not grant basic roles in a production environment, but you can grant them in a development or test environment.
Listing service accounts
You can list the user-managed service accounts in a project to help you audit service accounts and keys, or as part of a custom tool for managing service accounts.
You can't list the service agents or other Google-managed service accounts that might appear in your project's allow policy and audit logs. Google-managed service accounts aren't located in your project, and you can't access them directly.
Console
In the Google Cloud console, go to the Service accounts page.
Select a project.
The Service accounts page lists all of the user-managed service accounts in the project you selected.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Execute the
gcloud iam service-accounts list
command to list all service accounts in a project.Command:
gcloud iam service-accounts list
The output is the list of all user-managed service accounts in the project:
NAME EMAIL SA_DISPLAY_NAME_1 SA_NAME_1@PROJECT_ID.iam.gserviceaccount.com SA_DISPLAY_NAME_2 SA_NAME_2@PROJECT_ID.iam.gserviceaccount.com
REST
The
serviceAccounts.list
method lists every user-managed service account in your project.
Before using any of the request data, make the following replacements:
PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.
HTTP method and URL:
GET https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "accounts": [ { "name": "projects/my-project/serviceAccounts/sa-1@my-project.iam.gserviceaccount.com", "projectId": "my-project", "uniqueId": "123456789012345678901", "email": "sa-1@my-project.iam.gserviceaccount.com", "description": "My first service account", "displayName": "Service account 1", "etag": "BwUpTsLVUkQ=", "oauth2ClientId": "987654321098765432109" }, { "name": "projects/my-project/serviceAccounts/sa-2@my-project.iam.gserviceaccount.com", "projectId": "my-project", "uniqueId": "234567890123456789012", "email": "sa-2@my-project.iam.gserviceaccount.com", "description": "My second service account", "displayName": "Service account 2", "etag": "UkQpTwBVUsL=", "oauth2ClientId": "876543210987654321098" } ] }
C++
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C++ API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C#
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C# API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Go API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Java API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Python API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Edit a service account
The display name (friendly name) and description of a service account are commonly used to capture additional information about the service account, such as the purpose of the service account or a contact person for the account.
Console
In the Google Cloud console, go to the Service accounts page.
Select a project.
Click the email address of the service account that you want to rename.
Enter the new name in the Name box, then click Save.
gcloud
-
In the Google Cloud console, activate Cloud Shell.
At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
-
Execute the
gcloud iam service-accounts update
command to update a service account.Command:
gcloud iam service-accounts update \ SA_NAME@PROJECT_ID.iam.gserviceaccount.com \ --description="UPDATED_SA_DESCRIPTION" \ --display-name="UPDATED_DISPLAY_NAME"
The output is the renamed service account:
description: UPDATED_SA_DESCRIPTION displayName: UPDATED_DISPLAY_NAME name: projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com
REST
The
serviceAccounts.patch
method updates a service account.
Before using any of the request data, make the following replacements:
PROJECT_ID
: Your Google Cloud project ID. Project IDs are alphanumeric strings, likemy-project
.SA_ID
: The ID of your service account. This can either be the service account's email address in the formSA_NAME@PROJECT_ID.iam.gserviceaccount.com
, or the service account's unique numeric ID.SA_NAME
: The alphanumeric ID of your service account. This name must be between 6 and 30 characters, and can contain lowercase alphanumeric characters and dashes.- Replace at least one of the following:
UPDATED_DISPLAY_NAME
: A new display name for your service account.UPDATED_DESCRIPTION
: A new description for your service account.
HTTP method and URL:
PATCH https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID
Request JSON body:
{ "serviceAccount": { "email": "SA_NAME@PROJECT_ID.iam.gserviceaccount.com", "displayName": "UPDATED_DISPLAY_NAME", "description": "UPDATED_DESCRIPTION" }, "updateMask": "displayName,description" }
To send your request, expand one of these options:
You should receive a JSON response similar to the following:
{ "name": "projects/my-project/serviceAccounts/my-service-account@my-project.iam.gserviceaccount.com", "displayName": "My updated service account", "description": "An updated description of my service account" }
C++
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C++ API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
C#
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM C# API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Go
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Go API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Java
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Java API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
Python
To learn how to install and use the client library for IAM, see IAM client libraries. For more information, see the IAM Python API reference documentation.
To authenticate to IAM, set up Application Default Credentials. For more information, see Set up authentication for a local development environment.
What's next
- Learn how to disable and enable service accounts.
- Review the process for granting IAM roles to all types of principals, including service accounts.
- Explore how you can use role recommendations to downscope permissions for all principals, including service accounts.
- Understand how to attach service accounts to resources.
Try it for yourself
If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
Get started for free