Before you can make requests to Earth Engine through a client library, you must authenticate and use the resultant credentials to initialize the Earth Engine client. If you are making direct requests through the REST API, you need to use credentials to make authenticated requests. You may need credentials to authenticate to other Google Cloud services programmatically. This page describes the process of Authentication and Initialization for various environments.
Earth Engine Code Editor
Authentication and initialization are handled automatically. You may choose to route requests through a Cloud Project from your login at the upper right of the Code Editor.
Authentication with Earth Engine client library helpers
authentication helpers in
ee.data (for example,
ee.initialize() as shown in
Authentication with a
You can use Credentials for authentication with Earth Engine and other Google Cloud services. The following describes general purpose methods for obtaining credentials that may be used with Earth Engine or other Google Cloud services.
gcloud command line
interface is a set of tools to create and manage Google Cloud resources.
gcloud can help you create and manage OAuth2 credentials. The following
gcloud command (learn more about this
establishes credentials and sets an environment variable pointing to them:
gcloud auth application-default login --scopes='https://www.googleapis.com/auth/devstorage.full_control','https://www.googleapis.com/auth/earthengine'
Running that command on a machine with an Earth Engine client library will
create credentials that can be used to initialize the Earth
Engine client. Note that this authentication flow requires
gcloud to be
installed on a machine with browser access. Also note that you must specify
scopes when authenticating as an end-user (learn
The scopes in the above command are the most minimal required to use the Earth
If you are using a Colab notebook, you can
use the Colab
from google.colab import auth auth.authenticate_user()
If you are authenticating as a service account, you can obtain credentials using
Other methods include
authenticate_service_account in the Colab
and the methods described in the Cloud guide to authenticating as a service
Compute Engine Virtual Machine (VM)
If your code is running on a Compute Engine VM, a default service account is created for the environment. You may need to register the service account to use Earth Engine if the Cloud Project through which the VM was started is not registered for use with Earth Engine (commercial or non-commercial).
Once you have created credentials, you can use them to initialize an Earth Engine client. When you initialize, provide a Cloud Project through which Earth Engine calls are routed. To pick up default credentials created from through one of the methods described above, run:
credentials, project_id = google.auth.default() ee.Initialize(credentials, project='your-project')
Note that the scopes of credentials loaded from
determined from the compute environment and may not meet your needs.
Specifically, they may be more broad than you need for using Earth Engine.
Although broader scopes are useful for authenticating to other Google Cloud
clients, services or APIs, you may want to avoid overly broad scopes for
Also note that
your-project must have the Earth Engine API enabled and either
you, the service account or the project is registered to use Earth Engine. See
If you don't have a Cloud Project and can't create one, follow these instructions.
What if I cannot create a Cloud Project?
Some organisations control who can create Cloud Projects. If you receive an error on the Notebook Authenticator page when trying to create a project, there are a few things to try:
- Try to create a project directly to confirm whether or not you have the necessary permissions.
- Speak to the administrator of your organisation to find out what processes are available to have a project created.
- Create a project from a non-organizational account, and add the account you use for work as an Owner of the project. Note: some organizations have security policies which prevent access to OAuth clients from external projects.
- If you are running in a notebook, run
!earthengine authenticate --auth_mode=gcloud --quietin the notebook and carefully follow the instructions. (The
--quietflag is currently necessary to avoid a gcloud incompatibility when running in non-local Python environments. Future updates will make this unnecessary.) This authentication flow does not require having a Cloud Project, but does require having access to a machine with gcloud installed and a web browser.
Error: "Project has an incompatible OAuth2 Client configuration"
Cloud projects can only have one OAuth2 Client configuration. You can check if a Cloud project has an OAuth2 Client configuration set by checking the OAuth 2.0 Client IDs on the Credentials page. You need to either select another Cloud project that has a compatible configuration already set up by the Notebook Authenticator, or select or create a Cloud project with no OAuth2 clients. The authenticator will configure this project automatically. Unfortunately, the OAuth system doesn't allow users to delete configurations, so one must use a different project. This project does not have to be the same project that's used for other Earth Engine work. As an alternative, if you're using Colab, it is possible to use the default Google auth credentials. See the Colab and Initialization sections.
Error: "gcloud failed. Please check for any errors above and install gcloud if needed."
This error may occur if gcloud is not installed or not on your PATH. It may also
occur if you call
ee.Authenticate(auth_mode='gcloud') from within a notebook
code cell. Use
ee.Authenticate() instead, which will default to using notebook
mode authentication. If you cannot create a project, see the solution above.
What if I do not have access to a local machine to install gcloud?
If you are working in a web-only environment without access to a local terminal,
and you still need to use a remote terminal, you can still initialize the
command line tool by triggering the notebook mode by running the
authenticate --auth_mode=notebook command.
Error 400: redirect_uri_mismatch
You may obtain this error if authenticating on a remote machine without access
to a web browser. Try adding
--quiet if running
from the command line or
ee.Authenticate(quiet=True) if using the Python
client. This will require you to authenticate with
gcloud from a machine that
has access to a web browser.