working on improving the docs

Author: carl-adams-planet

docs/built-ins.md

@@ -0,0 +1,4 @@
+# Built-in Auth Client Profile Injection
+
+TODO: Document how applications may inject built-in auth client profiles for
+a smoother application user and developer experience.

docs/changelog.md

@@ -1,9 +1,9 @@
 # Changelog
 
-## 2.1.0 - 2025 TBD
+## 2.1.0 - 2025-??-??
 - Initial public release targeting integration with the
   [Planet Client for Python](https://github.com/planetlabs/planet-client-python).
 
-## [Unreleased: 2.0.*] - YYYY-MM-DD
+## [Unreleased: 2.0.*]
 - All releases in the 2.0.X series are development releases, even if not
   tagged as such. This work included some shakedowns of the release pipelines.

docs/configuration.md

@@ -9,11 +9,9 @@ AuthClient Configuration dictionaries may either be provided directly, or loaded
 from disk when saved in a `Profile` (See below).
 
 While it is possible to work directly with the lower level implementation
-classes, it is generally simpler to use the higher level management code in
-[planet_auth.Auth][], or the factory methods in [planet_auth.AuthClient][] 
-and [planet_auth.AuthClientConfig][] to configure and instantiate instances.
-Directly using the lower level implementations should not be necessary in
-most cases.
+classes, it is generally simpler to organize the working set of objects
+with an [Auth Context][planet_auth.Auth] instance created from one of the
+factory methods in [planet_auth_utils.PlanetAuthFactory][]
 
 A number of auth client implementations are provided.  Clients should
 select the one most appropriate for their use case.
@@ -28,19 +26,13 @@ Configuration:
 
 Profile Usage:
 ```python linenums="1"
-from planet_auth import Auth
-
-auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
 ```
 
 
 Direct Usage:
 ```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
+{% include 'snippets/auth-client-context-pl-legacy-direct.py' %}
 ```
 
 ### OAuth Clients
@@ -54,18 +46,16 @@ Configuration:
 
 Profile Usage:
 ```python linenums="1"
+{% include 'snippets/auth-client-context-from-saved-profile.py' %}
+
 from planet_auth import Auth
 
 auth_ctx = Auth.initialize_from_profile(profile="_profile_name_")
 ```
 
 Direct Usage:
 ```python linenums="1"
-from planet_auth import Auth
-auth_ctx = Auth.initialize_from_config_dict(
-    client_config={ ... content of auth_client.json ... },
-    token_file="/my_token_file.json"
-)
+{% include 'snippets/auth-client-context-oauth-direct.py' %}
 ```
 
 #### Auth Code with PKCE and Client Public Key

docs/examples-cli.md

@@ -0,0 +1,16 @@
+# CLI Examples
+
+## Embedding the `plauth` Command in Another `click` Program
+It is possible to embed the [`plauth`](/cli-plauth) command into other programs to
+present a unified experience that leverages the [planet_auth](/api)
+package for client authentication plumbing.  This is done by using
+a special version of the command that is configured for embedding.
+
+When using the embedded version of the command, the outer application
+must take on the responsibility of instantiating the auth context and
+handling command line options so that this context may be available
+to click commands that are outside the `plauth` root command.
+
+```python linenums="1"
+{% include 'cli/embed-plauth-click.py' %}
+```

docs/examples-client.md

@@ -0,0 +1,73 @@
+# Client Examples
+Client examples cover scenarios in which a program wishes to use
+the planet auth utilities as a client, obtaining credentials
+from authentication services so that they may be used to
+make authenticated requests to other network services.
+
+## OAuth Client Authentication
+A custom auth client profile may be used to configure the AuthClient
+to use an arbitrary OAuth2 auth service to obtain access tokens for
+use with application APIs.
+See [Configuration and Profiles](/configuration) for more information 
+on client types and profiles.
+
+1. Create a `~/.planet/<profile_name>/auth_client.json` or `~/.planet/<profile_name>/auth_client.sops.json` file.
+For example, to create a custom profile named "my-custom-profile", create the following:
+```json linenums="1" title="~/.planet/my-custom-profile/auth_client.json"
+{% include 'auth-client-config/oauth-auth-code-grant-public-client.json' %}
+```
+2. Initialize the client library with the specified profile.  Note: if the environment variable
+`PL_AUTH_PROFILE` is set, it will be detected automatically by [planet_auth_utils.PlanetAuthFactory][],
+and it will not be necessary to explicitly pass in the profile name:
+```python linenums="1"
+{% include 'auth-client/oauth/initialize-client-lib-on-disk-profile.py' %}
+```
+An alternative to creating a file on disk is to initialize_from_profile a client
+purely in memory.  For some runtime environments where local storage may
+not be available or trusted, this may be more appropriate:
+```python linenums="1"
+{% include 'auth-client/oauth/initialize-client-lib-in-memory.py' %}
+```
+3. Perform initial login to obtain and save long term credentials, if required
+by the configured profile.  An initial login is usually required for auth
+clients that act on behalf of a user and need to perform an interactive login.
+Clients configured for service operation may frequently skip this step:
+```python linenums="1"
+{% include 'auth-client/oauth/perform-oauth-initial-login.py' %}
+```
+4. Make authenticated requests:
+    * Option 1 - Using `requests`:
+```python linenums="1"
+{% include 'auth-client/oauth/make-oauth-authenticated-requests-request.py' %}
+```
+    * Option 2 - Using `httpx`:
+```python linenums="1"
+{% include 'auth-client/oauth/make-oauth-authenticated-httpx-request.py' %}
+```
+
+## Performing a Device Login
+The procedure for performing initial user login on a UI limited device
+is slightly different.  Rather than simply calling `login()`, it is necessary
+to initiate the process with a call to `device_login_initiate()`, display the
+returned information to the user so that the user may authorize the client
+asynchronously, and complete the process by calling `device_login_complete()`.
+This procedure only applies to clients that are permitted to use the
+Device Authorization OAuth flow.
+
+```python linenums="1"
+{% include 'auth-client/oauth/perform-oauth-device-login.py' %}
+```
+
+## Planet Legacy Authentication
+The proprietary Planet legacy authentication protocol is targeted for future
+deprecation.  It should not be used for any new development.
+
+### Initial Login
+```python linenums="1"
+{% include 'auth-client/planet-legacy/perform-legacy-initial-login.py' %}
+```
+
+### Authenticated `requests` Call
+```python linenums="1"
+{% include 'auth-client/planet-legacy/make-legacy-authenticated-requests-request.py' %}
+```

docs/examples-installation.md

@@ -0,0 +1,7 @@
+# Installation
+
+## Install from _PyPI.org_ using `pip`
+Install the required modules:
+```shell
+pip install planet-auth
+```

docs/examples-service.md

@@ -0,0 +1,50 @@
+# Service Examples
+Service examples cover scenarios in which a program wishes to use
+the planet auth utilities as a service, verifying the authenticity
+of access credentials presented to the service by a client.
+
+It should be noted that Services may also act as clients when making
+calls to other services.  When a service is acting in such a capacity,
+the [Client Examples](./examples-client.md) apply.
+When the service is acting on behalf of itself, it is likely that
+a [OAuth2 Client Credentials](./configuration.md#client-credentials-with-client-secret)
+configuration applies.
+
+When a service is acting on behalf of one of its clients... 
+(TODO: cover this.)
+
+## Verifying OAuth Clients
+The [planet_auth.OidcMultiIssuerValidator][] class is provided to assist with
+common OAuth client authentication scenarios.  This class can be configured
+with a single authority for normal operations, and may optionally be configured
+with a secondary authorities.  This allows for complex deployments such as
+the seamless migration between auth servers over time.
+
+This utility class may be configured for entirely local token validation,
+or may be configured to check token validity against the OAuth token inspection
+endpoint.  For most operations, local validation is expected to be used, as
+it is more performant, not needing to make blocking network calls, and more
+robust, not depending on external service availability.  For high value operations,
+remote validation may be performed which checks whether the specific access
+token has been revoked.
+
+Tokens are normally not long-lived. Token lifespans should be selected to
+strike a balance between security concerns and allow frequent use of local
+validation, and not overburden the token inspection endpoint.
+
+Checking tokens against the OAuth token inspection endpoint does require the
+use of OAuth clients that are authorized to use the endpoint, and may not
+be available to anonymous clients, depending on the auth server configuration.
+
+### Local Access Token Validation
+```python linenums="1" title="Basic usage of OidcMultiIssuerValidator. Validate access tokens locally."
+{% include 'service/flask--oidc-multi-issuer--local-only-validation.py' %}
+```
+
+### Local and Remote Access Token Validation
+```python linenums="1" title="Advanced usage of OidcMultiIssuerValidator. Validate access tokens against OAuth inspection endpoints using custom auth clients."
+{% include 'service/flask--oidc-multi-issuer--local-and-remote-validation.py' %}
+```
+
+## Verifying Planet Legacy Client
+This is not supported by this library.

docs/examples.md

@@ -1,6 +1,6 @@
 {
     "client_type": "oidc_auth_code_pubkey",
-    "auth_server": "https://account.planet.com/oauth2/aus2enhwueFYRb50S4x7",
+    "auth_server": "https://login.planet.com/",
     "client_id": "your_client_id",
     "client_privkey": "__private_key_literal_PEM__",
     "client_privkey_file": "__path_to_private_key_PEM_file__",

docs/examples/auth-client-config/oauth-auth-code-grant-confidential-client-pubkey.json

@@ -1,6 +1,6 @@
 {
     "client_type": "oidc_auth_code_secret",
-    "auth_server": "https://account.planet.com/oauth2/aus2enhwueFYRb50S4x7",
+    "auth_server": "https://login.planet.com/",
     "client_id": "your_client_id",
     "client_secret": "your_client_secret",
     "redirect_uri": "your_client_redirect_url__if_needed",

docs/examples/auth-client-config/oauth-auth-code-grant-confidential-client-secret.json

@@ -1,6 +1,6 @@
 {
     "client_type": "oidc_auth_code",
-    "auth_server": "https://account.planet.com/oauth2/aus2enhwueFYRb50S4x7",
+    "auth_server": "https://login.planet.com/",
     "client_id": "your_client_id",
     "redirect_uri": "client_redirect_url_for_network_hosted_handler__if_needed",
     "local_redirect_uri": "client_redirect_url_for_localhost_handler__if_needed",