planetlabs · carl-adams-planet · Apr 9, 2025 · Apr 10, 2025 · Apr 11, 2025 · Apr 12, 2025
diff --git a/.github/workflows/publish-pypi.yml b/.github/workflows/publish-pypi.yml
@@ -24,7 +24,7 @@ jobs:
           restore-keys: |
             ${{ runner.os }}-pip
 
-      - name: Build, verify, and upload to TestPyPI
+      - name: Build, verify, and upload to PyPI
         run: |
           pip install --upgrade nox
           nox -s build publish_pypi

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
diff --git a/.gitignore b/.gitignore
@@ -23,7 +23,9 @@ coverage.xml
 *.pyc
 
 # Editors
+.idea/
 .vscode/
 # Docs build
 site
 .venv
+venv
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,10 +19,12 @@ insofar as is practical within the scope of changes targeted to the next major r
 versioning, major releases do not guarantee backwards compatibility.  Stability is not guaranteed
 during the development cycle.
 
-During the development cycle of a new major release, `RELEASE-PLANNING-X.0.md` should be maintained
-with a brief summary of the major and breaking changes underpinning the reason for the upcoming
-major release version.  Upon release, this content is expected to be folded into package documentation
-as appropriate, and this file should be removed.
+During the development cycle of a new major release, a GitHub Project and Milestone should be
+created to track changes targeted the release.  A file such as `RELEASE-PLANNING-X.0.md` in the
+root of the source tree may be used for early development prior to the creation of a GitHub
+project, but should be retired when a new release becomes more formalized.  Upon release,
+all content is expected to be folded into package documentation as appropriate (announcements,
+company blog posts, changelogs, migration guides, etc.).
 
 When a new major release is ready, the development mainline branch will be renamed to `main`, and the
 old mainline branch will be renamed to `maint-X.0` and will be used as the base for maintenance releases.

diff --git a/README.md b/README.md
@@ -81,11 +81,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#branches) for more information on branches
 
 ##### Current Mainline Versions and Branches
 
-| Version | Status        | Branch                                                                                 | Documentation                                                                                                | Initial Release | End of Active Development | End of Maintenance | Notes                                                                                                                        |
-|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------|
-| 3.x     | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD                                                                                                          | TBD             | TBD                       | TBD                | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). |
-| 2.x     | `active`      | [`main`](https://github.com/planetlabs/planet-client-python/tree/main)                 | [Planet Labs Python Client v2 on Readthedocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023      | TBD                       | TBD                |                                                                                                                              |
-| 1.x     | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1)                     | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/)              | April 2017      | April 2023                | TBD                |                                                                                                                              |
+| Version | Status        | Branch                                                                                 | Documentation                                                                                                | Initial Release | End of Active Development | End of Maintenance | Notes                                                                                           |
+|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|-------------------------------------------------------------------------------------------------|
+| 3.x     | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | [Planet Labs Python Client on ReadTheDocs.io](https://planet-sdk-for-python.readthedocs.io/en/latest/)       | TBD             | TBD                       | TBD                | See [3.0.0 Release Milestone](https://github.com/planetlabs/planet-client-python/milestone/31). |
+| 2.x     | `active`      | [`main`](https://github.com/planetlabs/planet-client-python/tree/main)                 | [Planet Labs Python Client v2 on ReadTheDocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023      | TBD                       | TBD                |                                                                                                 |
+| 1.x     | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1)                     | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/)              | April 2017      | April 2023                | TBD                |                                                                                                 |
 
 ## Installation and Quick Start
 

diff --git a/RELEASE.md b/RELEASE.md
@@ -54,7 +54,6 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t
      * _`version`_: [https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/](https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/) - Should point to version `X.YY.ZZ`.
    * Pre-release versions should _not_ impact the default version of the documentation. Pre-release version may be published as the `latest` version.
 
-
 ## Local publishing
 
 Publishing to testpypi and pypi can also be performed locally with:

diff --git a/docs/auth/auth-dev-app-managed-apikey.md b/docs/auth/auth-dev-app-managed-apikey.md
@@ -0,0 +1,39 @@
+# Application Managed Sessions - Planet API Key
+
+## Planet API Key Sessions
+Legacy applications that need to continue to support Planet API keys may do so
+until API keys are deprecated. This method should not be adopted for new
+development if possible.
+
+### Examples - Planet API Keys
+
+#### In Memory Session State
+Once provided with an API key, an application may operate with the API key
+in memory indefinitely without the need to prompt the user for re-authentication.
+```python linenums="1" title="Access APIs using Planet API keys in memory"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__api_key.py' %}
+```
+
+#### Version 2 Compatibility
+The SDK continues to support files written by version 2 of the SDK to save
+auth state.
+```python linenums="1" title="Access APIs using Planet API keys using the on disk file format used by older versions of the SDK"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_legacy__api_key.py' %}
+```
+
+```json linenums="1" title="Legacy API Key file example"
+{% include 'auth-session-management/legacy_api_key_file.json' %}
+```
+
+#### Session State Shared with CLI
+```python linenums="1" title="Access APIs using Planet API keys with CLI managed shared state on disk"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__api_key.py' %}
+```
+
+####  Session State Saved to Application Storage
+
+```python linenums="1" title="Access APIs using Planet API keys with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__api_key.py' %}
+```
+
+----
diff --git a/docs/auth/auth-dev-app-managed-oauth.md b/docs/auth/auth-dev-app-managed-oauth.md
@@ -0,0 +1,174 @@
+# Application Managed Sessions - OAuth2
+
+If an application cannot or should not use a login session initiated by the
+[`planet auth`](../../cli/cli-reference/#auth) CLI command, the application will be
+responsible for managing the process on its own, persisting session state as
+needed.
+
+Application managed sessions may be used with all authentication protocols.
+Application developers may control whether sessions are visible to the CLI.
+This is managed with the `save_state_to_storage` parameter on the `planet.Auth`
+constructor methods illustrated below.
+
+The process varies depending on the authentication protocol used.
+Depending on the use case, applications may need to support multiple authentication
+methods, just as the [`planet`](../../cli/cli-reference) CLI command supports interacting with Planet APIs
+using either a user or a service user account.
+
+## OAuth2 Session for Users
+User session initialization inherently involves using a web browser to
+complete user authentication.  This architecture allows for greater security
+by keeping the user's password from being directly exposed to the application
+code. This also allows for flexibility in user federation and multifactor
+authentication procedures without the complexity of these needing to
+be exposed to the application developer who is focused on geospatial
+operations using the Planet platform, and not the nuances of user
+authentication and authorization.
+
+### OAuth2 User Client Registration
+Developers of applications must register client applications with Planet, and
+will be issued a Client ID as part of that process.  Developers should register
+a client for each distinct application so that end-users may discretely manage
+applications permitted to access Planet APIs on their behalf.
+
+See [OAuth2 Client Registration](http://docs.planet.com/develop/authentication/#interactive-client-registration)
+for more information.
+
+### With a Local Web Browser
+In environments where a local browser is available, the Planet SDK library can manage
+the process of launching the browser locally, transferring control to the Planet
+authorization services for session initialization, and accepting a network
+callback from the local browser to regain control once the authorization
+process is complete. At a network protocol level, this establishes the user
+login session using the OAuth2 authorization code flow.
+
+To use this method using the SDK, the following requirements must be met:
+
+* The application must be able to launch a local web browser.
+* The web browser must be able to connect to Planet services.
+* The application must be able to listen on a network port that is accessible
+  to the browser.
+
+#### Examples - OAuth2 Authorization Code Flow
+
+##### In Memory Session State
+When an application cannot safely store user session state, it may operate purely in memory. When this
+method is used, the user will be prompted to complete the login process each time the application is run.
+
+```python linenums="1" title="Login as a user using a local browser with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_authcode__with_browser.py' %}
+```
+
+##### Session State Shared with CLI
+Applications may save their session state in a way that is shared with the CLI.  With saved state,
+the user will only be prompted to complete the login process once.
+```python linenums="1" title="Login as a user using a local browser with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_authcode__with_browser.py' %}
+```
+
+#####  Session State Saved to Application Storage
+Applications may save their session state to application provided storage.  With saved state,
+the user should only be prompted to complete the login process once.  Using application provided storage
+will result in the session state not being shared with the CLI.
+
+Applications needing to use their own storage will do so by providing
+the `Auth` layer in the SDK with a custom implementation of the
+[`planet_auth.ObjectStorageProvider`](https://planet-auth.readthedocs.io/en/latest/api-planet-auth/#planet_auth.ObjectStorageProvider)
+abstract base class.  See examples below for more details.
+
+```python linenums="1" title="Login as a user using a local browser with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_authcode__with_browser.py' %}
+```
+
+### Without a Local Web Browser
+In environments where a local web browser is not available, additional steps must
+be taken by the application author to initialize the user session.
+For example, a remote shell to a cloud environment is not likely
+to be able to open a browser on the user's desktop or receive network callbacks
+from the user's desktop browser.  In these cases, a browser is
+still required.  To complete login in such a case, the SDK will generate a URL and a
+verification code that must be presented to the user. The user must visit the
+URL out of band to complete the login process while the application polls for
+the completion of the login process using the SDK. At a network protocol
+level, this establishes the user login session using the OAuth2 device
+code flow.
+
+To use this method using the SDK, the following requirements must be met:
+
+* The application must be able to connect to Planet services.
+* The application must be able to display instructions to the user, directing
+  them to a web location to complete login.
+
+As above, this may be done with state only persisted in memory, with state
+shared with the CLI, or with state saved to application provided storage.
+
+#### Examples - OAuth2 Device Code Flow
+
+##### In Memory Session State
+```python linenums="1" title="Login as a user using an external browser with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_user_devicecode__external_browser.py' %}
+```
+
+##### Session State Shared with CLI
+```python linenums="1" title="Login as a user using an external browser with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_user_devicecode__external_browser.py' %}
+```
+
+#####  Session State Saved to Application Storage
+```python linenums="1" title="Login as a user using an external browser with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_user_devicecode__external_browser.py' %}
+```
+
+## OAuth2 Session for Service Accounts
+Service account session initialization is simpler than user session
+initialization, and does not require a web browser.
+
+While preserving session state for user sessions was a concern driven
+in part by a concern for the user experience of using a web browser for
+initialization, for service accounts it remains a concern to avoid
+throttling by the authorization service.
+
+If applications are expected to run longer than the life of an access token
+(a few hours), then in memory operations are acceptable (for example: a long-running
+data processing job).  If application lifespan is short and frequent,
+then the application should take steps to persist the session state (for
+example: a command line utility run repeatedly from a shell with a short lifespan).
+
+Like the session state itself, service account initialization parameters are
+sensitive, and it is the responsibility of the application to store them
+securely.
+
+At a network protocol level, OAuth2 service account sessions are implemented
+using the OAuth2 authorization code flow.  This carries with it some additional
+security concerns, discussed in
+[RFC 6819 §4.4.4](https://datatracker.ietf.org/doc/html/rfc6819#section-4.4.4).
+Because of these considerations, service accounts should only be used for
+workflows that are independent of a controlling user.
+
+As above, this may be done with state only persisted in memory, with state
+shared with the CLI, or with state saved to application provided storage.
+
+### OAuth2 M2M Client Registration
+Service accounts are managed under the
+**OAuth Clients** panel on the [Planet Insights Account](https://insights.planet.com/account/#/) page.
+
+See [Sentinel Hub Authentication](https://docs.sentinel-hub.com/api/latest/api/overview/authentication/) for further information.
+
+### Examples - OAuth2 Client Credentials Flow
+
+#### In Memory Session State
+```python linenums="1" title="Access APIs using a service account with in memory only state persistance"
+{% include 'auth-session-management/app_managed_auth_state__in_memory__oauth_m2m.py' %}
+```
+
+#### Session State Shared with CLI
+```python linenums="1" title="Access APIs using a service account with sessions persisted on disk and shared with the CLI"
+{% include 'auth-session-management/app_managed_auth_state__on_disk_cli_shared__oauth_m2m.py' %}
+```
+
+####  Session State Saved to Application Storage
+```python linenums="1" title="Access APIs using a service account with sessions persisted to application provided storage"
+{% include 'auth-session-management/app_managed_auth_state__app_custom_storage__oauth_m2m.py' %}
+```
+
+----