Announcement: On November 13, 2024, all users will need to use a Cloud project in order to access Earth Engine. After this date, continued individual access without a Cloud project will require an exception.

Service Accounts

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.

Create a private key for the service account

Once you have a service account, click the menu for that account (), then Create key > JSON. Download the JSON key file.

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. Ensure it is not possible for anyone to gain unauthorized access to it, since they would be able to access Google APIs on your behalf. Never store your private key in a public place, like a shared folder or a source repository. If you misplace your private key, you can easily revoke access to a service account and create a new one using the Cloud Console. See this guide for details.

Register the service account to use Earth Engine

If you don't use a registered Cloud project to access Earth Engine, you can use this page to register your service account for use with the Earth Engine API. Once you've successfully registered your service account, follow the instructions that appear on the confirmation screen to enable access to the Earth Engine API.

Use a service account with a private key

To authenticate to Earth Engine using a service account:

Create and download a JSON private key file (.private-key.json) for the service account.

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.

What do I do if I get an invalid_grant error?

OAuth2 can be very sensitive to clock skew. If you're certain you've set everything up correctly and your Google contact has verified that the service account has been approved, check to see if your computer's clock is synchronized to network time.

For Ubuntu systems, the call to sync your computer's clock is:

ntpdate ntp.ubuntu.com

For systems using OS X, open System Preferences > Date & Time > Date & Time (again) and select Set date and time automatically.

Use a default service account

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)