Authentication

Public services need no sign-in. This page covers the two cases that do: secured ArcGIS content, and a USGS API key for higher rate limits.

ArcGIS Online and Portal

Sign in once, and every portal and services call made without an explicit token= uses your session. The token is sent only to the portal’s own hosts, never to an unrelated public service.

One-time setup, for each ArcGIS Online organization or Enterprise portal:

  1. In the portal, go to Content, then New item, then Developer credentials, and create OAuth 2.0 credentials.

  2. Add the redirect URL http://127.0.0.1:8765/callback.

  3. Note the client id. No client secret is needed.

Then sign in whichever way fits.

In a notebook or script, through the browser (enterprise single sign-on such as SAML or eAuth works):

from georest.restesri import auth

auth.login("https://myorg.maps.arcgis.com", client_id="abc123")
auth.status()   # who you are and until when; never the token itself

In ArcGIS Pro, reusing Pro’s own session (run in Pro’s Python):

from arcgis.gis import GIS
from georest.restesri import auth

gis = GIS("Pro")
auth.set_token(gis._con.token, portal=gis.url, refresh=lambda: gis._con.token)

For a long-running process, such as an MCP server, sign in once from a terminal:

georest-login --portal https://myorg.maps.arcgis.com --client-id abc123

That saves a refresh token to ~/.georest/esri_credentials.json, which later processes pick up automatically until it expires (two weeks by default, set by your organization). Then run the command again. georest-login --logout removes it, and the GEOREST_ESRI_PORTAL and GEOREST_ESRI_CLIENT_ID environment variables can stand in for the flags.

USGS Water Data API key

The Water Data API works without a key, but anonymous use is limited to a few queries per hour. For more, get a free key and set USGS_API_KEY in the environment, or call georest.restusgs.waterdata.set_api_key() once at startup.

The key is sent only in the X-Api-Key header, never in a URL, so it cannot leak through an error message or a log line. Results carry the remaining request budget when the server reports it (fc["rate_limit"]). When the server answers 429 with a wait georest will not sit through, it raises georest.restusgs.waterdata.RateLimitError, whose retry_after says when to try again.