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.
Set up authentication.
Select the tab for how you plan to use the samples on this page:
Console
When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.
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.
C#
To use the .NET samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
C++
To use the C++ samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
Go
To use the Go samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
Java
To use the Java samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
Python
To use the Python samples on this page in a local development environment, install and initialize the gcloud CLI, and then set up Application Default Credentials with your user credentials.
- Install the Google Cloud CLI.
-
To initialize the gcloud CLI, run the following command:
gcloud init
-
If you're using a local shell, then create local authentication credentials for your user account:
gcloud auth application-default login
You don't need to do this if you're using Cloud Shell.
For more information, see Set up authentication for a local development environment in the Google Cloud authentication documentation.
REST
To use the REST API samples on this page in a local development environment, you use the credentials you provide to the gcloud CLI.
Install the Google Cloud CLI, then initialize it by running the following command:
gcloud init
For more information, see Authenticate for using REST in the Google Cloud authentication documentation.
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 to projects, folders, and organizations.
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 that might appear in your project's allow policy and audit logs. Service agents 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
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 Before you begin.
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 Before you begin.
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 Before you begin.
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 Before you begin.
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 Before you begin.
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/[email protected]", "projectId": "my-project", "uniqueId": "123456789012345678901", "email": "[email protected]", "description": "My first service account", "displayName": "Service account 1", "etag": "BwUpTsLVUkQ=", "oauth2ClientId": "987654321098765432109" }, { "name": "projects/my-project/serviceAccounts/[email protected]", "projectId": "my-project", "uniqueId": "234567890123456789012", "email": "[email protected]", "description": "My second service account", "displayName": "Service account 2", "etag": "UkQpTwBVUsL=", "oauth2ClientId": "876543210987654321098" } ] }
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
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 Before you begin.
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 Before you begin.
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 Before you begin.
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 Before you begin.
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 Before you begin.
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/[email protected]", "displayName": "My updated service account", "description": "An updated description of my service account" }
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