Service Accounts

To use Earth Engine, an application must authenticate to Google. This allows Google to verify that the app has access to the API and to the data it is requesting. The Earth Engine API uses a standard protocol called OAuth 2.0 for authentication. Service accounts are a way for your app to use OAuth 2.0 to authenticate to Google.

What is a service account?

A service account is an account associated with an application rather than an end user. You should use one when you, as a developer, want to write code that talks to Earth Engine without using your personal account. A service account only has access to things that you grant it access to, and you can revoke a service account's access at any time.

How do I create a service account?

If you created an App Engine project, a default service account for that project is created automatically. To determine if your project has a default service account, go to the Cloud Console menu (menu) and select IAM & Admin > Service accounts. (Choose the project if prompted.)

  • If you don't see an entry for App Engine default service account, click Create service account. Choose a service account name. For Role, choose Project > Editor.
  • Once you have a service account, click the menu for that account (more_vert), then Create key. Download a key file as a JSON file.

Learn more about creating service accounts.

Register the service account to use Earth Engine

Use this form to request Earth Engine access for your service account. The service account email address should look like: or Until the App Engine service account is registered, you will not be able to use it to access the Earth Engine API.

Use the service account with Google App Engine

To use a service account in an App Engine app:

  1. Create and download a JSON private key file.
  2. Copy the JSON file into the directory with the app.yaml file.
  3. In App Engine Python code, authenticate like this:
    service_account = ''
    credentials = ee.ServiceAccountCredentials(service_account, 'privatekey.json')

For complete examples, check out the example App Engine apps in the Earth Engine API repository.

What is a private key?

Each service account comes with a private key, which is a special file that allows programs to access Google APIs on behalf of your service account. You should treat this file very carefully, making sure 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 can easily revoke access to a service account and create a new one using the Cloud Console.

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 whitelisted, 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:


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