Authentication

Planet APIs use different authentication mechanisms depending on the base domain. The two primary domains are api.planet.com and sentinel-hub.com. See the following sections for details on how to authenticate with each domain.

api.planet.com Authentication

API endpoints under the api.planet.com domain use API keys for programmatic access. API keys grant access to the platform equivalent to the key owner and should be protected as being as sensitive as the user password.

After youn sign up, your API key can be found on your Account page under the "My Settings" tab. You may only have one active API key at a time.

In addition to obtaining your API key from the user settings page, it can be retrieved using the planet CLI that is part of the Planet Python SDK.

APIs under the api.planet.com domain accept API keys using several mechanisms:

• HTTP Basic Authentication - Basic HTTP Authentication (described in RFC 7617), API keys are presented to the APIs by setting the username to the API key. The password should be left empty.
• Authorization HTTP Header - The Authorization header, API keys are presented to the APIs with the api-key scheme.
• URL query parameter - URL query parameters, API keys are presented to the APIs using the api_key parameter.

Most APIs accept HTTP Basic and this method is preferred. Many accept multiple methods, but some may only accept the Authorization header or URL query parameter. The URL query parameter has been implemented by some APIs to support limitations present in many tile streaming clients where modifying HTTP headers may be difficult. Refer to specific API documentation for details on what methods are supported.

Obtaining your Planet API key

CLI

Initialize the CLI using your username and password to obtain and save and view your API key

planet auth init
planet auth value

Python SDK

Use Planet SDK

import planet
import getpass


def auth_init_sample(api_key, my_app_username, my_app_password):
    # The SDK's Auth context and saved state can be initialized from a username
    # and password, or an API key.
    # Applications MUST NOT save the user's password.
    if api_key:
        plauth = planet.Auth.from_key(api_key)
    else:
        plauth = planet.Auth.from_login(my_app_username, my_app_password)

    plauth.store()  # Saves API Key to ~/.planet.json for SDK use.
    print(
        f"Sample SDK Auth context initialized with API Key, which has been saved to local disk: {plauth.value}"
    )
    return plauth.value


if __name__ == "__main__":
    api_key = input("API Key: ")
    if not api_key:
        username = input("Email: ")
        password = getpass.getpass(prompt="Password: ")
    else:
        username = None
        password = None

    auth_init_sample(api_key, username, password)

warning

While Python code is inherently open, the mechanisms used by the planet auth init CLI and the SDK to obtain a user API key are not documented as part of the Planet stable APIs and are targeted for deprecation in the near future.

Using your Planet API Key with HTTP Basic

CURL

Use API Key obtained from the your settings page with CURL

curl -u "${PL_API_KEY}:" https://api.planet.com/data/v1/searches

CURL + CLI

Use API Key initialized with SDK CLI with CURL

curl -u "`planet auth value`:" https://api.planet.com/data/v1/searches

CLI

The SDK CLI uses HTTP Basic in its implementation

planet data search-list

Python SDK

The SDK uses HTTP Basic in its implementation. This implementation detail is hidden from the SDK user.

import asyncio

import planet


async def list_searches_example():
    # The default session created with planet.Session() will automatically pick-up
    # the API key from ~/.planet.json (as saved by Auth.store()), or the PL_API_KEY
    # environment variable.
    #
    # Alternatively, applications may use a Auth context of their own construction
    # so that they may control the user experience of managing and entering API keys.
    # for example:
    #     planet.Session(auth=planet.Auth.from_key("PLAK_User_API_Key"))
    async with planet.Session(auth=planet.Auth.from_env("MY_APP__PL_API_KEY")) as sess:
        data_api_client = sess.client("data")
        saved_searches = []
        async for saved_search in data_api_client.list_searches():
            print(saved_search)
            saved_searches.append(saved_search)

    return saved_searches


if __name__ == "__main__":
    asyncio.run(list_searches_example())

Using your Planet API Key with Authorization Header

CURL

Use API Key obtained from your settings page with CURL

curl -H "Authorization: api-key ${PL_API_KEY}" https://api.planet.com/data/v1/searches

CURL + CLI

Use API Key initialized with SDK CLI with CURL

curl -H "Authorization: api-key `planet auth value`" https://api.planet.com/data/v1/searches

note

The SDK internals do not use this method, so it is not available to make calls to Planet APIs using the SDK or the CLI.

Using your Planet API Key with URL Parameter

CURL

Use API Key obtained from the user's settings page with CURL

curl "https://api.planet.com/basemaps/v1/mosaics?api_key=${PL_API_KEY}"

CURL + CLI

Use API Key initialized with SDK CLI with CURL

curl "https://api.planet.com/basemaps/v1/mosaics?api_key=`planet auth value`"

note

The SDK internals do not use this method, so it is not available for making calls to Planet APIs using the SDK or the CLI.

---

sentinel-hub.com Authentication

API endpoints under the sentinel-hub.com domain use OAuth2 access tokens for programmatic access. Access tokens are obtained using the Client Credentials flow using client IDs and client secrets that are managed from the OAuth Clients panel in the Account app.

See Sentinel Hub Authentication for further information.

See RFC 6749 for more information on the OAuth2 Framework.