Configure App Engine service accounts

App Engine applications require aservice accountto access other Google Cloud services and execute tasks.

There are two types of service accounts in App Engineand any service account in your Cloud project can be assigned to act as eitherthe app-level default or per-version service account:

  • App-level default service account - This service account is used for all of your deployedservices when you don't configure a "per-version service account". You can chooseto assign a service account that you created or use theauto-created default service account thatgets created when you initially deploy a service to your Cloud project. For example, theApp Engine default service account (PROJECT_ID@appspot.gserviceaccount.com).

  • Per-version service account - A service account configured as the identityfor a specific version of your deployed service. When deploying an existingversion or a new version, you can specify a service account to act as that version'sidentity. For example, if a version requires permissions that differ from theapp-level default service account, you can assign a service account that is specific to that version.

View your configured service accounts

To view the current app-level default service account, run thegcloud app describecommand.

To view the service account used by a deployed version:

gcloud

Run thegcloud app versions describe command:

gcloudappversionsdescribeVERSION_ID--service=SERVICE_NAME

Replace:

  • VERSION_ID with the ID of the version.
  • SERVICE_NAME with the name of the service that you created.

Console

  1. Go to the App EngineVersions tab in the console.Go to Versions
  2. Locate the email address of your App Engineversion-specific service account. Example:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Assign an app-level default service account

By default, the app-level default service account is the auto-createdPROJECT_ID@appspot.gserviceaccount.com service account. You can assign another serviceaccount to act as the app-level default service account using Google Cloud CLI,Google Cloud console, or Admin API.

Specify an app-level default service account during app creation

During the initial App Engine application creation process,you can choose to assign a service account that youcreated or use the auto-createdPROJECT_ID@appspot.gserviceaccount.com service account to act as the default.

To create a your App Engine application and assign an app-leveldefault service account, you can use one of the following:

gcloud

Run thegcloud app create command:

gcloudappcreate--service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

  • SERVICE_ACCOUNT_NAME with the name of the service account that you created.
  • PROJECT_ID with ID of the Google Cloud project in which you want to assign the service account.

Console

  1. Go to the App Engine page:

    Go to App Engine

  2. Create a Google Cloud project.

  3. In theCreate App section, select a service account fromIdentity and API access.

Update the app-level default service account for your app

To update the app-level default service account for your application, you can useone of the following to assign a new service account:

Important: Only versions deployed after the update will use the new app-leveldefault service account. All previously deployed versions will not use the new app-leveldefault service account until you re-deploy that version.

gcloud

Run thegcloud app update command.

gcloudappupdate--service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

  • SERVICE_ACCOUNT_NAME with the name of the service account that you created.
  • PROJECT_ID with ID of the Google Cloud project in which you want to assign theservice account.

Each new version that you deploy hereafter uses the new app-level default serviceaccount unless you explicitly assign a version-specific service account.

Console

  1. Go to the App EngineApplication Settings tab in the console and clickEdit Application Settings.

    Go to Application Settings

  2. Choose an app-level default service account fromSelect a Service account and clickSave.

    You will be redirected to theApplication Settings tab where you can view the emailaddress of your updated app-level default service account. Example:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com.

    Each new version that you deploy hereafter uses the new app-level default serviceaccount unless you explicitly assign a version-specific service account.

Deploy with a version-specific service account

You can set a version-specific service account only during the deployment of newversions. Using a version-specific service account lets you grant differentprivileges to each application version, based on the specific tasks it performs,and avoid granting more privileges than necessary.

You must have anexisting serviceaccount before deploying your application. Your version-specific service accountmust be in the same project where you deploy your application.

Note: If a version-specific service account is specified in both theapp.yaml fileand in thegcloud CLI, thegcloud setting takes precedence.

After May 15, 2024, Artifact Registry hosts images for thegcr.io domain inGoogle Cloud projects without previous Container Registry usage. If you deploy anexisting application in a new project created after this date, the service accountmight not have the required permissions to deploy the app. To grant therequired permissions, seeDeploying to App Engine.

Set a version-specific service account

gcloud

Run thegcloud app deploy command:

gcloudappdeploy--service-account=SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

  • SERVICE_ACCOUNT_NAME with the name of the service account that you created.
  • PROJECT_ID with ID of the Google Cloud project in which you want to assignthe service account. Your version-specific service account must be in thesame project where you deploy your application.

app.yaml

In yourapp.yamlfile, specify your service account by adding theservice_accountelement:

service_account:SERVICE_ACCOUNT_NAME@PROJECT_ID.iam.gserviceaccount.com

Replace:

  • SERVICE_ACCOUNT_NAME with the name of the service account that you created.
  • PROJECT_ID with ID of the Google Cloud project in which you want to assignthe service account. Your version-specific service account must be in thesame project where you deploy your application.

App Engine default service account

The default App Engine service account is automatically createdwhen you use App Engine.

Depending on your organization policy configuration, the default service account might automatically be granted theEditor role on your project. We strongly recommend that you disable the automatic role grant by enforcing theiam.automaticIamGrantsForDefaultServiceAccounts organization policy constraint. If you created your organization after May 3, 2024, this constraint is enforced by default.

If you disable the automatic role grant, you must decide which roles to grant to the default service accounts, and thengrant these roles yourself.

If the default service account already has the Editor role, we recommend that you replace the Editor role with less permissive roles.To safely modify the service account's roles, usePolicy Simulator to see the impact of the change, and thengrant and revoke the appropriate roles.

To learn how to grant roles to service accounts and other principals, seeManage access to projects, folders, andorganizations.

After May 15, 2024, Artifact Registry hosts images for thegcr.io domain inGoogle Cloud projects without previous Container Registry usage. If you deploy anexisting application in a new project created after this date, the service accountmight not have the required permissions to deploy the app. To grant therequired permissions, seeDeploying to App Engine.

For modifying permissions, deleting, and restoring your service accounts, seeCreating and managing service accounts.

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-15 UTC.