List and edit service accounts

This page explains how to list and edit service accounts using theIdentity and Access Management (IAM) API, the Google Cloud console, and thegcloud command-line tool.

Before you begin

  • Enable the IAM API.

    Roles required to enable APIs

    To enable APIs, you need the Service Usage Admin IAM role (roles/serviceusage.serviceUsageAdmin), which contains theserviceusage.services.enable permission.Learn how to grant roles.

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

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

      If you're using a local shell, then create local authentication credentials for your user account:

      gcloudauthapplication-defaultlogin

      You don't need to do this if you're using Cloud Shell.

      If an authentication error is returned, and you are using an external identity provider (IdP), confirm that you have signed in to the gcloud CLI with your federated identity.

    For more information, see Set up ADC 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.

      If you're using an external identity provider (IdP), you must first sign in to the gcloud CLI with your federated identity.

    For more information, seeAuthenticate for using REST in the Google Cloud authentication documentation.

  • UnderstandIAM 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:

For more information about granting roles, seeManage access to projects, folders, and organizations.

You might also be able to get the required permissions throughcustom roles or otherpredefined roles.

To learn more about these roles, seeService Accounts roles.

IAM basic roles also contain permissions to manage serviceaccounts. You should not grant basic roles in a production environment, but you can grant them in adevelopment or test environment.

Listing service accounts

You can list theuser-managed service accounts in a projectto help you audit service accounts and keys, or as part of a custom tool formanaging service accounts.

You can't list theservice agents that might appear in yourproject's allow policy and audit logs. Service agents aren't located in yourproject, and you can't access them directly.

Console

  1. In the Google Cloud console, go to theService accounts page.

    Go to Service accounts

  2. Select a project.

    TheService accounts page lists all of the user-managed service accountsin the project you selected.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud 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.

  2. Execute thegcloud 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                    EMAILSA_DISPLAY_NAME_1SA_NAME_1@PROJECT_ID.iam.gserviceaccount.comSA_DISPLAY_NAME_2SA_NAME_2@PROJECT_ID.iam.gserviceaccount.com

C++

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMC++ API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&project_id){iam::IAMClientclient(iam::MakeIAMConnection());intcount=0;for(auto&sa:client.ListServiceAccounts("projects/"+project_id)){if(!sa)throwstd::move(sa).status();std::cout <<"ServiceAccount successfully retrieved: " <<sa->name()              <<"\n";++count;}if(count==0){std::cout <<"No service accounts found in project: " <<project_id              <<"\n";}}

C#

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMC# API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

usingSystem;usingSystem.Collections.Generic;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassServiceAccounts{publicstaticIList<ServiceAccount>ListServiceAccounts(stringprojectId){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});varresponse=service.Projects.ServiceAccounts.List("projects/"+projectId).Execute();foreach(ServiceAccountaccountinresponse.Accounts){Console.WriteLine("Name: "+account.Name);Console.WriteLine("Display Name: "+account.DisplayName);Console.WriteLine("Email: "+account.Email);Console.WriteLine();}returnresponse.Accounts;}}

Go

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMGo API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// listServiceAccounts lists a project's service accounts.funclistServiceAccounts(wio.Writer,projectIDstring)([]*iam.ServiceAccount,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}response,err:=service.Projects.ServiceAccounts.List("projects/"+projectID).Do()iferr!=nil{returnnil,fmt.Errorf("Projects.ServiceAccounts.List: %w",err)}for_,account:=rangeresponse.Accounts{fmt.Fprintf(w,"Listing service account: %v\n",account.Name)}returnresponse.Accounts,nil}

Java

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMJava API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.ServiceAccount;importjava.io.IOException;publicclassListServiceAccounts{publicstaticvoidmain(String[]args)throwsIOException{// TODO(Developer): Replace the below variables before running.StringprojectId="your-project-id";listServiceAccounts(projectId);}// Lists all service accounts for the current project.publicstaticIAMClient.ListServiceAccountsPagedResponselistServiceAccounts(StringprojectId)throwsIOException{// Initialize client that will be used to send requests.// This client only needs to be created once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){IAMClient.ListServiceAccountsPagedResponseresponse=iamClient.listServiceAccounts(String.format("projects/%s",projectId));for(ServiceAccountaccount:response.iterateAll()){System.out.println("Name: "+account.getName());System.out.println("Display name: "+account.getDisplayName());System.out.println("Email: "+account.getEmail()+"\n");}returnresponse;}}}

Python

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMPython API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

fromtypingimportListfromgoogle.cloudimportiam_admin_v1fromgoogle.cloud.iam_admin_v1importtypesdeflist_service_accounts(project_id:str)->List[iam_admin_v1.ServiceAccount]:"""Get list of project service accounts.    project_id: ID or number of the Google Cloud project you want to use.    returns a list of iam_admin_v1.ServiceAccount    """iam_admin_client=iam_admin_v1.IAMClient()request=types.ListServiceAccountsRequest()request.name=f"projects/{project_id}"accounts=iam_admin_client.list_service_accounts(request=request)returnaccounts.accounts

REST

TheserviceAccounts.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 projectID. 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:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts" | Select-Object -Expand Content

APIs Explorer (browser)

Open themethod reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and clickExecute.

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"    }  ]}

Edit a service account

The display name (friendly name) and description of a service account arecommonly used to capture additional information about the service account, suchas the purpose of the service account or a contact person for the account.

Console

  1. In the Google Cloud console, go to theService accounts page.

    Go to Service accounts

  2. Select a project.

  3. Click the email address of the service account that you want to rename.

  4. Enter the new name in theName box, then clickSave.

gcloud

  1. In the Google Cloud console, activate Cloud Shell.

    Activate Cloud Shell

    At the bottom of the Google Cloud console, aCloud 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.

  2. Execute thegcloud 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_DESCRIPTIONdisplayName:UPDATED_DISPLAY_NAMEname: projects/PROJECT_ID/serviceAccounts/SA_NAME@PROJECT_ID.iam.gserviceaccount.com

C++

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMC++ API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

namespaceiam=::google::cloud::iam_admin_v1;[](std::stringconst&name,std::stringconst&display_name){iam::IAMClientclient(iam::MakeIAMConnection());google::iam::admin::v1::PatchServiceAccountRequestrequest;google::iam::admin::v1::ServiceAccountservice_account;service_account.set_name(name);service_account.set_display_name(display_name);google::protobuf::FieldMaskupdate_mask;*update_mask.add_paths()="display_name";*request.mutable_service_account()=service_account;*request.mutable_update_mask()=update_mask;autoresponse=client.PatchServiceAccount(request);if(!response)throwstd::move(response).status();std::cout <<"ServiceAccount successfully updated: "            <<response->DebugString() <<"\n";}

C#

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMC# API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

usingSystem;usingGoogle.Apis.Auth.OAuth2;usingGoogle.Apis.Iam.v1;usingGoogle.Apis.Iam.v1.Data;publicpartialclassServiceAccounts{publicstaticServiceAccountRenameServiceAccount(stringemail,stringnewDisplayName){varcredential=GoogleCredential.GetApplicationDefault().CreateScoped(IamService.Scope.CloudPlatform);varservice=newIamService(newIamService.Initializer{HttpClientInitializer=credential});// First, get a ServiceAccount using List() or Get().stringresource="projects/-/serviceAccounts/"+email;varserviceAccount=service.Projects.ServiceAccounts.Get(resource).Execute();// Then you can update the display name.serviceAccount.DisplayName=newDisplayName;serviceAccount=service.Projects.ServiceAccounts.Update(serviceAccount,resource).Execute();Console.WriteLine($"Updated display name for {serviceAccount.Email} "+"to: "+serviceAccount.DisplayName);returnserviceAccount;}}

Go

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMGo API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

import("context""fmt""io"iam"google.golang.org/api/iam/v1")// renameServiceAccount renames a service account.funcrenameServiceAccount(wio.Writer,email,newDisplayNamestring)(*iam.ServiceAccount,error){ctx:=context.Background()service,err:=iam.NewService(ctx)iferr!=nil{returnnil,fmt.Errorf("iam.NewService: %w",err)}// First, get a ServiceAccount using List() or Get().resource:="projects/-/serviceAccounts/"+emailserviceAccount,err:=service.Projects.ServiceAccounts.Get(resource).Do()iferr!=nil{returnnil,fmt.Errorf("Projects.ServiceAccounts.Get: %w",err)}// Then you can update the display name.serviceAccount.DisplayName=newDisplayNameserviceAccount,err=service.Projects.ServiceAccounts.Update(resource,serviceAccount).Do()iferr!=nil{returnnil,fmt.Errorf("Projects.ServiceAccounts.Update: %w",err)}fmt.Fprintf(w,"Updated service account: %v",serviceAccount.Email)returnserviceAccount,nil}

Java

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMJava API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

importcom.google.cloud.iam.admin.v1.IAMClient;importcom.google.iam.admin.v1.GetServiceAccountRequest;importcom.google.iam.admin.v1.PatchServiceAccountRequest;importcom.google.iam.admin.v1.ServiceAccount;importcom.google.iam.admin.v1.ServiceAccountName;importcom.google.protobuf.FieldMask;importjava.io.IOException;publicclassRenameServiceAccount{publicstaticvoidmain(String[]args)throwsIOException{// TODO(developer): Replace the variables before running the sample.StringprojectId="your-project-id";StringserviceAccountName="my-service-account-name";StringdisplayName="your-new-display-name";renameServiceAccount(projectId,serviceAccountName,displayName);}// Changes a service account's display name.publicstaticServiceAccountrenameServiceAccount(StringprojectId,StringserviceAccountName,StringdisplayName)throwsIOException{// Construct the service account email.// You can modify the ".iam.gserviceaccount.com" to match the service account name in which// you want to delete the key.// See, https://cloud.google.com/iam/docs/creating-managing-service-account-keys?hl=en#deletingStringserviceAccountEmail=serviceAccountName+"@"+projectId+".iam.gserviceaccount.com";// Initialize client that will be used to send requests.// This client only needs to be created once, and can be reused for multiple requests.try(IAMClientiamClient=IAMClient.create()){// First, get a service account using getServiceAccount or listServiceAccountsGetServiceAccountRequestserviceAccountRequest=GetServiceAccountRequest.newBuilder().setName(ServiceAccountName.of(projectId,serviceAccountEmail).toString()).build();ServiceAccountserviceAccount=iamClient.getServiceAccount(serviceAccountRequest);// You can patch only the `display_name` and `description` fields. You must use//  the `update_mask` field to specify which of these fields you want to patch.serviceAccount=serviceAccount.toBuilder().setDisplayName(displayName).build();PatchServiceAccountRequestpatchServiceAccountRequest=PatchServiceAccountRequest.newBuilder().setServiceAccount(serviceAccount).setUpdateMask(FieldMask.newBuilder().addPaths("display_name").build()).build();serviceAccount=iamClient.patchServiceAccount(patchServiceAccountRequest);System.out.println("Updated display name for "+serviceAccount.getName()+" to: "+serviceAccount.getDisplayName());returnserviceAccount;}}}

Python

To learn how to install and use the client library for IAM, seeIAM client libraries. For more information, see theIAMPython API reference documentation.

To authenticate to IAM, set up Application Default Credentials. For more information, seeBefore you begin.

fromgoogle.cloudimportiam_admin_v1fromgoogle.cloud.iam_admin_v1importtypesdefrename_service_account(project_id:str,account:str,new_name:str)->types.ServiceAccount:"""Renames service account display name.    project_id: ID or number of the Google Cloud project you want to use.    account: ID or email which is unique identifier of the service account.    new_name: New display name of the service account.    """iam_admin_client=iam_admin_v1.IAMClient()get_request=types.GetServiceAccountRequest()get_request.name=f"projects/{project_id}/serviceAccounts/{account}"service_account=iam_admin_client.get_service_account(request=get_request)service_account.display_name=new_namerequest=types.PatchServiceAccountRequest()request.service_account=service_account# You can patch only the `display_name` and `description` fields.# You must use the `update_mask` field to specify which of these fields# you want to patch.# To successfully set update mask you need to transform# snake_case field to camelCase.# e.g. `display_name` will become `displayName`request.update_mask="displayName"updated_account=iam_admin_client.patch_service_account(request=request)returnupdated_account

REST

TheserviceAccounts.patch method updates a service account.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: Your Google Cloud projectID. 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 serviceaccount's unique numeric ID.
  • SA_NAME: The alphanumeric ID of yourservice account. This name must be between 6 and 30 characters, and can contain lowercasealphanumeric 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:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login , or by usingCloud Shell, which automatically logs you into thegcloud CLI . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

curl -X PATCH \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID"

PowerShell (Windows)

Note: The following command assumes that you have logged in to thegcloud CLI with your user account by runninggcloud init orgcloud auth login . You can check the currently active account by runninggcloud auth list.

Save the request body in a file namedrequest.json, and execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://iam.googleapis.com/v1/projects/PROJECT_ID/serviceAccounts/SA_ID" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open themethod reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and clickExecute.

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"}

What's next

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

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.