Skip to main content

age-oauth

age-oauth simplifies access to an ArcGIS Enterprise via OAuth 2.0 credentials (application or user), and eliminates the need (and bad security practice) of storing username/passwords/tokens in your scripts. age-oauth also stores and indexes multiple connection profiles - these connections could be different scopes on the same Portal, or multiple Portals, or a combination of the two. Moreover, multiple connections can be used in any automation by simply calling them by their storage label.

Pre-Requisites and OAuth 2.0 Item Creation

This README assumes that you already have the permissions needed to create OAuth 2.0 app/developer tokens on an ArcGIS Enterprise instance.

age-oauth supports two paths for OAuth 2.0; user and application.

Auth type Use when you need to... OAuth flow
user access assets as yourself auth code + refresh token
application access assets as an application client credentials

If you are creating an OAuth item and do not have your own web server (e.g., you're just running manual or automated scripts), you will need to use either an out-of-band (OOB) URI for the redirect value (for user auth type) or a dummy referrer value (for app auth type) when prompted:

Default OOB URI (user): urn:ietf:wg:oauth:2.0:oob Dummy referrer (app): https://localhost

Application Permissions

On ArcGIS Enterprise 11.4+, OAuth 2.0 App credentials can be configured with application permissions, or depending on Portal configuration and the privileges of the creating user, it could be set to impersonate the user. Please verify the permissions you give the application in ArcGIS Enterprise and coordinate with your administrators before using it for unattended automation. You've been warned!

Install

Use pip to install age-oauth.

Minimal

This is fine if you're installing into an ArcGIS Pro conda environment, e.g. arcgispro-py3 or if you don't need the arcgis package.

python -m pip install age-oauth

Full

This will install arcgis and arcgis-mapping and give you full ArcGIS API for Python access.

python -m pip install "age-oauth[full]"

Use

Add a Connection

Connections are added via CLI, and can be created interactively or non-interactively.

Add Connection Interactively

Run:

age-oauth connections add

You'll be prompted for the connection settings, including whether the connection authenticates as a user or as an application.

Connections are given a friendly label so scripts can refer to them without embedding portal URLs, client IDs, secrets, or tokens.

Add Connection Non-interactively

You can also add the Portal non-interactively. For a new user connection type:

age-oauth connections add `
  --label "some user" `
  --portal "https://somewhere.com/portal" `
  --auth-type user `
  --verify-ssl false `
  --client-id "client_id_value" `
  --client-secret "client_secret_value"

For a new application credential:

age-oauth connections add `
  --label "some app" `
  --portal "https://somewhere.com/portal" `
  --auth-type app `
  --referer "https://localhost" `
  --verify-ssl true `
  --client-id "client_id_value" `
  --client-secret "client_secret_value"

Private/Custom CAs

NOTE: If your ArcGIS Enterprise uses a private CA, you can pass the CA's path to --verify-ssl.

First Authentication / Onboarding

User and application OAuth credential types are logged in the same way. For a user connection profile, a browser challenge-response will be presented.

age-oauth login --connection "some user"

You'll see:

Opening browser for ArcGIS Enterprise OAuth sign-in...

A browser will open to your Portal login screen. Sign in, grab the authorization code and paste it back into the shell where you are being prompted for it.

age-oauth will swap the authorization code for an access token, a refresh token, and an expiration timestamp. This is then securely stored in your user profile. If all is successful, you'll see:

New access_token acquired!  Expires in: 2:00:00
Token is for user: your.username

For application connection profiles, age-oauth will cache, access and fetch new access tokens as needed in accordance with a Portal's expiration policy.

Validate Connection and Identity

To verify, do:

age-oauth whoami --connection "some user"

In the case of a user you should see:

your.username

In the case of an application, you should see:

Type:        application
Application: Application Name
App ID:      XXXXXXXXXXXXXXXX
Item ID:     XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
Owner:       your.username

Your OAuth credentials are now onboarded and you can start using them programmatically.

Python API

Now, you can use it in Python!

from age_oauth import Connection, list_connections

# Create an authenticated arcgis.gis.GIS object by label
portal_conn = Connection(connection="connection label")
gis = portal_conn.get_gis()

# Create an authenticated session by index
portal_conns = list_connections()
print(portal_conns)

# result
#	['some user', 'some application', 'another connection']

# Initialize multiple Connection objects in the same script

my_conns = {
    conn.label: conn.get_gis()
    for conn in list_connections()
}

user_conn = my_conns["some user"]
app_conn = my_conns["some application"]

No username/passwords, no tokens, no janky PKI decryption in your scripts. age-oauth handles negotiation and refresh automatically.

Rotation of refresh_token for user access

While calling the library programmatically will automatically update the refresh_token associated with the active connection automatically (3 day duration), users or admins can also call it interactively.

age-oauth token --rotate-refresh-token --portal <portal label>

If the refresh_token is still good, the command does nothing.

Storage

Portal profiles are stored per-user under your OS home (profile) directory. Nothing is stored globally:

Windows

%APPDATA%\age_oauth\

Each connection contains the following:

connections/
    my_portal_<uuid>/
        .env         # OAuth settings and tokens
        meta.json    # metadata

Why does this exist?

It is tempting to write scripts like:

gis = GIS("https://my-portal.com/portal", "username", "password")

# or

gis = GIS("https://my-portal.com/portal", token="abcdef12345abcdef12345abcdef...")

Or do any number of other sketchy things. This creates both security and maintainability problems, with increased technical debt at best and compromise at worst.

In a secure setting, we want revocable credentials, clear ownership of the access object, an expiration policy and centralized management. This is exactly what the OAuth workflow gives you when it's properly used.

age-oauth is designed to make this way (the more secure way) also the more convenient way.

But why not just use API keys?

ArcGIS Enterprise developer API keys are useful, but they have short lifetimes and require manual renewal. This introduces friction into automations you may need to run under your human-user persona. OAuth supports refresh tokens that can be reused indefinitely to get new access tokens. Going through the up-front setup to establish OAuth client access pays off in the long run by giving you way cleaner scripts that are easier to maintain, can be passed around without fear of leaking your credentials, and helps your security folks sleep better at night.

Metadata

Release files for age-oauth 0.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for age-oauth 0.2.1
File Size Uploaded Provenance Actions
age_oauth-0.2.1.tar.gz 38.0 kB With provenance Details for age_oauth-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for age-oauth 0.2.1
File Interpreter ABI Platform Actions
age_oauth-0.2.1-py3-none-any.whl Python 3 none any Details for age_oauth-0.2.1-py3-none-any.whl

Total release size: 76.3 kB

Release files / age_oauth-0.2.1.tar.gz

Download URL age_oauth-0.2.1.tar.gz
Size 38.0 kB
Tags Source
SHA-256 checksum
How to use checksums
f5fb4f86d67385b42f3d4d7c10ed10abd6f4d508697d070191ac1dc4ca24c9af
BLAKE2b-256 checksum
How to use checksums
895b7e6c814b1e9ecc93bf13866ea41d09b74b987332011789bfef9583af59cb
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

Release files / age_oauth-0.2.1-py3-none-any.whl

Download URL age_oauth-0.2.1-py3-none-any.whl
Size 38.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
da090f2fc0bbc7638fba2702b8b5dbb9aa5a01a70e067054f33f925329ecd892
BLAKE2b-256 checksum
How to use checksums
796fa08c80e654afd0851afa46890e9f41d2189873987b916249306b90520fa7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

Security for age-oauth 0.2.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for age_oauth-0.2.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page