Service Accounts

To use Earth Engine, you must authenticate to Google. This allows Google to verify that you have access to the API, and to confirm that you are authorized to access the data that you are using. The Earth Engine API uses a standard protocol called OAuth 2.0 for authentication. There are several ways that you can use OAuth 2.0 to authenticate to Google. Service accounts are one of them.

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?

Follow the instructions on the Google Developers Console to create a service account.

Whitelist the service account

Send the email address associated with the client ID and secret to either your Earth Engine contact or [e-mail] so that it can be whitelisted for Earth Engine access. The service account email address should look like: [e-mail]. Please include in the email requesting access the Gmail account of the Earth Engine user responsible for the app and a brief description of the intended purpose of the app. Until this happens, you will not be able to use this service account 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. Download a P12 private key from the Google Developers Console.
2. Convert the private key of that service account to a `.pem` file:

   openssl pkcs12 -in downloaded-privatekey.p12 -nodes -nocerts > privatekey.pem
             

3. Copy the .pem file into the directory with the app.yaml file.
4. In App Engine Python code, authenticate like this:

   service_account = '[e-mail]'
   credentials = ee.ServiceAccountCredentials(service_account, 'privatekey.pem')
   ee.Initialize(credentials)
             

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, too. Never store your private key in a public place, like a shared folder or a source repository. Fortunately, you can easily revoke access to a service account and create a new one if, for example, you misplace your private key.

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:

ntpdate ntp.ubuntu.com
      

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