Service Accounts

  • A service account is used for applications or the REST API, not the Earth Engine Python API directly.

  • Creating a service account involves setting it up in your Google Cloud project's IAM & Admin section.

  • A private key in JSON format is needed for the service account to access Google APIs.

  • The Cloud project containing the service account must be registered to use Earth Engine and have the Earth Engine API enabled.

  • Service accounts can be used with a private key file for authentication or you can use a default service account.

A service account is an account associated with an application rather than an end user. You may need to use a service account to authenticate to Earth Engine if you are developing an app or using the REST API. Learn more about authenticating with service accounts.

Create a service account

First, create a Google Cloud project if you have not already done so.

You can manage the service accounts for your Cloud project by going to the Cloud Console menu () and selecting IAM & Admin > Service accounts. (Choose the project if prompted.)

To create a new service account, click the + CREATE SERVICE ACCOUNT link.

If you created an App Engine project, you may already have a default service account (App Engine default service account) for that project. If you are setting up an App Engine project, for the service account Role, choose Project > Editor.

Configure the service account to use Earth Engine

All service accounts are created within a Cloud project, which may be the same project used for your App Engine app or Cloud VM. Ensure that the Cloud project is registered to access Earth Engine, and that the Earth Engine API is enabled on the project. All service accounts in the project with the correct permissions will have access to Earth Engine.

Authenticate to Earth Engine using Application Default Credentials

Application Default Credentials (ADC) is the recommended way to authenticate in unattended environments (like Cloud Run or Compute Engine) without managing private keys manually. 

import google.auth
import ee

credentials, project_id = google.auth.default()
ee.Initialize(credentials, project='my-ee-project')

Authenticate with a private key

If your application needs to authenticate using a service account private key (not recommended for production environments where ADC can be used):

  1. Create a private key for the service account:
    • Go to the Service Accounts page in the Cloud Console.
    • Click the menu for the account (), then Create key > JSON.
    • Download the JSON key file.
  2. Keep your key file safe. The key file is a special file that allows programs to access Google APIs on behalf of your service account. Never store your private key in a public place. If you misplace your private key, you can revoke access to a service account and create a new one using the Cloud Console. See Create and delete service account keys for details.
  3. Test the following Python code from wherever you put the .private-key.json file: 
    import ee
service_account = 'my-service-account@...gserviceaccount.com'
credentials = ee.ServiceAccountCredentials(service_account, '.private-key.json')
ee.Initialize(credentials)

If you are able to initialize without an error, your service account is ready to use.

Use a default service account on Compute Engine

If you are using a default service account, you first need to modify the access scopes of the VM for the Compute Engine Service Account to "Allow full access to all Cloud APIs". (If you are using default service accounts in Dataflow or App Engine, this step is not necessary.)

To authenticate to Earth Engine using a default service account, use the following code:

from google.auth import compute_engine
import ee
credentials = compute_engine.Credentials(scopes=['https://www.googleapis.com/auth/earthengine'])
ee.Initialize(credentials)

Set up REST API access

If the service account is to make computations using the REST API, you need to give it project-level permission, specifically the Earth Engine Resource Viewer role. Depending on your project configuration, you may also need to give the service account the Service Usage Consumer role. See Access Control page for more information about project permissions required to use Earth Engine.

Troubleshooting

Error: invalid_grant

OAuth2 can be very sensitive to clock skew. If you're certain you've set everything up correctly, check to see if your computer's clock is synchronized to network time.

Error: "Provided scope(s) are not authorized" when exporting to Cloud Storage

If you see this error when running in a Cloud Run task, don't set the scopes argument when creating credentials (e.g., in google.auth.default(scopes=...)). Specifying scopes can interfere with the default permissions in this environment.