CLI Managed Sessions

For simple programs and scripts, it is easiest for the program to defer session management to the planet auth CLI. This method will store session information in the user's home directory in the ~/.planet.json file and ~/.planet/ directory. The Python SDK will use the information saved in these locations to make API calls.

When this approach is taken, the authentication session will be shared between actions taken by the planet utility and those taken by programs built using the SDK. Changes made by one will impact the behavior of the other.

CLI managed sessions can be used for all authentication protocols supported by the SDK library.

Requirements and Limitations:

• The program must have read and write access to the user's home directory.
• This method requires that the end-user has access to and understands the planet CLI command needed to manage authentication.
• This approach should not be used on public terminals or in cases where the user's home directory cannot be kept confidential.

Initialize Session - CLI Login

Session login can be performed using the following command. This command can be used to initialize sessions using any of the supported authentication methods, and will default to creating an OAuth2 user session. Refer to the command's --help for more information.

Initialize session using planet CLI.

planet auth login

A particular configuration may be selected by using the --auth-profile option. planet-user is the default, but may be overridden by the runtime environment.

Initialize session using planet CLI, forcing the built-in user interactive OAuth2 login flow.

planet auth login --auth-profile planet-user

Initialize session using planet CLI, forcing the use of the specified service principal.

planet auth login --auth-client-id <your-client-id> --auth-client-secret <your-client-secret>

Initialize session using planet CLI, forcing the use of a legacy Planet API key.

planet auth login --auth-api-key <your-api-key>

Using Saved Session

Using a CLI managed session is the default behavior for SDK functions. Developing an application that uses a CLI managed session requires no additional action by the developer. When a developer chooses to create an application that behaves in this way, it will most often be done implicitly by relying on SDK default behavior, but it may also be done explicitly.

CLI Selected Session

The default behavior of the SDK is to defer which session is loaded to CLI.

import json
import planet


def example_main():
    # By default, the Planet SDK will be instantiated with the default auth
    # session configured by `planet auth` and saved to disk.  This default
    # initialization will also inspect environment variables for configuration.
    pl = planet.Planet()

    # Use the SDK to call Planet APIs.
    # Refreshing OAuth2 access tokens will be managed automatically by the SDK.
    for item in pl.data.list_searches():
        print(json.dumps(item, indent=2, sort_keys=True))


if __name__ == '__main__':
    example_main()

import json
import planet
import sys


def example_main():
    # Explicitly load the user's auth session from disk.  The user must have
    # invoked `planet auth login` before this program is run, or the API calls
    # will fail.  This will not initialize a new session.
    plsdk_auth = planet.Auth.from_user_default_session()

    if not plsdk_auth.is_initialized():
        print(
            "Login required. Execute the following command:\n\n\tplanet auth login\n"
        )
        sys.exit(99)

    # Alternatively, an application can call this, which will attempt to
    # initialize the session if it is not already initialized.
    # plsdk_auth.ensure_initialized(allow_open_browser=True, allow_tty_prompt=True)

    # Create a Planet SDK object that uses the loaded auth session.
    sess = planet.Session(plsdk_auth)
    pl = planet.Planet(sess)

    # Use the SDK to call Planet APIs.
    # Refreshing access tokens will be managed automatically by the SDK.
    for item in pl.data.list_searches():
        print(json.dumps(item, indent=2, sort_keys=True))


if __name__ == '__main__':
    example_main()

Application Selected Session

Applications may be developed to always select a specific CLI managed profile. This may be useful in cases where an application wishes to guide the user experience towards expecting an auth session that is separate from the default sessions used by the CLI.

In cases where the application has access to the user's home directory and saved sessions, forcing the use of a particular profile circumvents the user's CLI managed preferences.

Note: This first example does not create the session my-app-profile. This must be created either through a separate code path as show in the Application Managed Sessions guide, or by using a CLI command to copy an existing profile such as planet auth profile copy planet-user my-app-profile.

import json
import planet
import sys


def example_main():
    # Explicitly load the user's auth session from disk for a specific
    # authentication session ("profile").  The user must have invoked
    # `planet auth login` before this program is run or the program
    # must have performed a login() elsewhere prior to this example.
    # If this has not been done, the API calls will fail.  This example
    # does not initialize a new session.
    plsdk_auth = planet.Auth.from_profile(profile_name="my-app-profile")

    # If required, how to login depends on what is configured in the specific
    # profile.  See other examples for login calls.
    if not plsdk_auth.is_initialized():
        print(
            "Login required. Execute the following command:\n\n\tplanet auth login --auth-profile my-cli-managed-profile\n"
        )
        sys.exit(99)

    # Create a Planet SDK object that uses the loaded auth session.
    sess = planet.Session(plsdk_auth)
    pl = planet.Planet(sess)

    # Use the SDK to call Planet APIs.
    # Refreshing access tokens will be managed automatically by the SDK.
    for item in pl.data.list_searches():
        print(json.dumps(item, indent=2, sort_keys=True))


if __name__ == '__main__':
    example_main()

It is also possible to force the use of the SDK's built-in OAuth2 application ID for interactive user applications. This capability is provided for developer convenience, primarily for smaller programs and scripts. Larger applications developed for multiple users should register a unique application ID.

This second example also initiates a login and does not save session state to storage. This means this example does not depend on the CLI, and may be considered a simple example of an Application Managed Session.

import json
import planet


def example_main():
    # Load the OAuth2 user-interactive client configration that is built-into the SDK.
    # This configuration is shared with the `planet` CLI command.
    # When save_state_to_storage is true, sessions will be shared with the
    # CLI and saved to the user's home directory.  When save_state_to_storage
    # is false, the state will only be persistent in memory and the
    # user will need to login each time the application is run.
    plsdk_auth = planet.Auth.from_profile("planet-user",
                                          save_state_to_storage=True)

    plsdk_auth.ensure_initialized(allow_open_browser=True,
                                  allow_tty_prompt=True)

    # Create a Planet SDK object that uses the loaded auth session.
    sess = planet.Session(plsdk_auth)
    pl = planet.Planet(sess)

    # Use the SDK to call Planet APIs.
    # Refreshing access tokens will be managed automatically by the SDK.
    for item in pl.data.list_searches():
        print(json.dumps(item, indent=2, sort_keys=True))


if __name__ == "__main__":
    example_main()

---