Authentication

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

Authentication Protocols

At the HTTP protocol level, API endpoints under the api.planet.com domain use several distinct mechanisms for client authentication, depending on the use case:

OAuth2 Authorization Code Grant (Interactive User) - API access as the end-user, using OAuth2 user access tokens. This is the preferred way for user interactive applications to authenticate to Planet APIs. A registered client application and a web browser are required to initialize a session. This method is considered the most secure for user access, and supports multi-factor and federated authentication mechanisms.

💡 The Planet Python SDK includes the planet CLI, a registered app that can initialize a session and manage token refresh automatically.

OAuth2 Client Credenital Grant (Machine-to-Machine) - API access as a service user that is independent of any human Planet user, using OAuth2 machine-to-machine (M2M) access tokens. This is the new preferred way for automated processes to authenticate to Planet APIs that must operate without a human user. No web browser is required, but this method carries some additional security considerations.
API Key - API access as an end-user using a simple fixed string bearer key. API keys grant access to the platform equivalent to that of the key's owner and should be protected as being as sensitive as the owner's password.

Authentication Protocol Support

Work to unify authentication practices across the Planet Insights Platform APIs and SDKs is ongoing.

	OAuth2 Authorization Code Grant	OAuth2 Client Credentials Grant	API Key	Planet Python SDK	Sentinel Hub Python SDK
`api.planet.com`	✅	🚧 Under Development	✅	✅	❌
`services.sentinel-hub.com`	✅	✅	❌	🚧 Proposed	✅
Self-service Client Management	❌	✅ OAuth2 Client Registration	✅ Obtaining your API Key	N/A	N/A
Planet Python SDK	✅ (Since 3.0)	✅ (Since 3.0)	✅	N/A	N/A
Sentinel Hub Python SDK	❌	✅	❌	N/A	N/A

OAuth2

Planet OAuth2 access tokens will work for all Planet APIs underneath both the api.planet.com and services.sentinel-hub.com domains.

OAuth2 authentication requires that the client possess an access token to make API calls. Access tokens are obtained by the client from a Planet authorization server that is separate from the API servers. Once obtained by the client, access tokens are then presented to API services to assert the client's right to make API calls.

Unlike Planet API keys, access tokens do not last forever for a variety of reasons and must be regularly refreshed by the client before their expiration, or the client may experience an interruption. But, clients should only refresh these tokens when necessary. Clients should not refresh access tokens for every API call; clients that misbehave in this way will be throttled by the authorization service, potentially losing access to APIs.

When using the Planet Python SDK, many of the details of obtaining and refreshing OAuth2 access tokens will be taken care of for you. For developers writing their own applications without the SDK, they will be responsible for implementing their own OAuth2 client.

OAuth2 defines many different ways to obtain access tokens, and a full discussion is beyond the scope of this Planet API guide. Please refer to the Resources below for more information. Planet broadly divides OAuth2 use cases into user-interactive and machine-to-machine use cases, as described in this guide.

OAuth2 to Planet Entity Mapping

Because OAuth2 is inherently more complex than other authentication mechanisms, it is useful to have an understanding of how the components of the Planet Insights Platform are mapped to OAuth2 defined roles and entities.:

OAuth2	Planet
Resource Owner	A Human user of the Planet Services.
Resource Server	A Planet Insights Platform API service. This includes all APIs under `api.planet.com` and `services.sentinel-hub.com`.
Client	Software written to access Planet APIs. This includes interactive applications acting on behalf of a user, as well as userless automated processes acting on their own behalf. Under OAuth2, "service accounts" are classified as clients, not as a type of user. Such clients are sometimes referred to as "machine-to-machine" (M2M) clients.
Authorization Server	Service responsible for issuing access tokens to clients. Planet operates two authorizations servers: `https://login.planet.com/` for user interactive client applications, and `https://services.sentinel-hub.com/auth/realms/main` for userless M2M clients.

OAuth2 Scopes

OAuth2 scopes are used by clients to specify the level of access required to Planet APIs. Users may grant or revoke a client's request. Clients should only request the scopes that are necessary to perform their intended operations. This mechanism allows users to contain the behavior of each client, keeping them within expected bounds. Clients may be restricted as to which scopes they may request, regardless of user authorization.

Scope	Description
`planet`	Scope to request access to all Planet APIs on behalf of the user or service account.
`offline_access`	Scope to request refresh tokens. This may only be requested by clients that access APIs on behalf of a user. M2M clients may not request this scope. Refresh tokens allow a client continued access to the API without reprompting a user to login with a browser.
`openid`	Scope to request an Open ID Connect (OIDC) identity token along with the OAuth2 access token. The identity token provides the client with user information, whereas the access token is used to make requests against resource servers on the user's or client's behalf. This scope will also grant access to standard OIDC userinfo endpoint on the authorization server.
`profile`	Scope to request user profile information. Used in conjunction with the `openid` scope.
`email`	Scope to request the user's email address.

OAuth2 Access Token Details

Planet access tokens are JSON Web Tokens (JWTs) that conform to the OAuth 2.0 Access Token Profile.

Access tokens are intended for use by API endpoints and should generally be treated as opaque by clients. However, since they are JWTs, they may be inspected by clients. Planet does not guarantee the stability of undocumented claims. Applications that do inspect tokens should only rely on claims documented here as part of the platform APIs:

JWT Claim	Required	Description
`exp`	Required	The expiration time of the token, given as an integer specifying the number of seconds since the epoch.

Using OAuth2 Access Tokens

All APIs that accept OAuth2 access tokens do so using the Authorization HTTP Header with the Bearer scheme prefixing the access token.

Authorization: Bearer <access_token>

OAuth2 access tokens managed by the CLI or the SDK may be used with CURL or other external programs. The procedure is the same for User Interactive and M2M sessions, differing only by providing a --auth-profile option to the CLI.

See sections below for examples of how to initialize the CLI managed session.

CURL + CLI

Use OAuth2 Access Token managed by the SDK CLI with CURL
curl -H "Authorization: Bearer `planet --auth-profile planet-user auth print-access-token`" https://api.planet.com/data/v1/searches

Authorization Code Grant (Interactive User)

Planet supports the OAuth2 authorization code flow and OAuth2 device code flow for clients accessing APIs on behalf of a user.

OAuth2 user session initialization inherently involves using a web browser to complete user authentication. This architecture allows for greater security by keeping the user's credentials from being directly exposed to the application. 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.

In contrast to Planet API keys, OAuth2 user sessions depend on session state that changes over time. This state must be persisted and updated by the application for a smooth user experience. The Planet Python SDK used by the examples below handles this for the user, as well as handling the details of launching a local web browser to complete the user authentication process.

Initializing with the Planet CLI and SDK for Python

Full SDK Documentation

See SDK Configuration for full details on environmental factors that may impact SDK and CLI behavior in these examples.

CLI
CLI + Python SDK
Python SDK

Initialize the CLI using OAuth2 for user session

planet auth login --auth-profile planet-user

Use the Planet SDK with an OAuth2 user session initialized by and shared with the CLI
import json
import planet
import sys


def example():
    # Load the user's preferred auth session from disk.  The user must have
    # invoked `planet auth login` before this program is run, or the API calls
    # will fail.  This does not initialize a new session, which involves
    # invoking a web browser to complete the OAuth user login exchange.
    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)

    # 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()

Use the Planet SDK with an OAuth2 user session initialized by the application and utilizing the SDK's built-in OAuth2 application ID.  Forcing the use of the SDK's built-in OAuth2 application ID is provided as a developer convenience.
import json
import planet


def example():
    # 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=False)

    if not plsdk_auth.is_initialized():
        plsdk_auth.user_login(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()

Client Credentials Grant (Machine-to-Machine)

Limitations with OAuth Client Credentials Grant

OAuth2 machine-to-machine (M2M) access tokens are currently available for use with services.sentinel-hub.com APIs. Work to support api.planet.com is ongoing.

At this time, API key authentication is recommended for M2M workflows.

OAuth2 machine-to-machine (M2M) sessions provide a way for clients to use OAuth2 authentication mechanisms for use cases that are decoupled from the lifecycle of a human end-user.

In contrast to OAuth2 user sessions, M2M sessions do not require a web browser for session initialization. Due to the implementation differences that enable this, the threat model that should be considered when protecting client initialization and session state information is also different, as discussed in RFC 6819 §4.4.4.

Sentinel Hub Authentication

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

The endpoint for requests tokens is the following:

https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token

Once you have a token, do use it for authenticating all your requests within its validity period. While tokens do not last forever, they do last a reasonable amount of time, and sufficiently long that they can be reused. The information of how long each token lasts is embedded in the token itself in the exp claim, and can be read from there.

Do not fetch a new token for each API request you make. Token requests are rate limited, so if you are getting an HTTP 429 error, that means you are requesting too many tokens.

The following are examples of requesting access tokens in CURL, Python, and JavaScript. Replace <your client id> with your client ID and <your client secret> with your client secret.

CURL
Python
JavaScript

CURL
curl --request POST --url https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token
  --header 'content-type: application/x-www-form-urlencoded'
  --data 'grant_type=client_credentials&client_id=<your client id>'
  --data-urlencode 'client_secret=<your client secret>'

Python
from oauthlib.oauth2 import BackendApplicationClient
from requests_oauthlib import OAuth2Session

# Your client credentials
client_id = '<client_id>'
client_secret = '<client_secret>'

# Compliance hook to properly raise server-side errors
def sentinelhub_compliance_hook(response):
    response.raise_for_status()
    return response

# Create OAuth2 session for machine-to-machine auth (Client Credentials)
client = BackendApplicationClient(client_id=client_id)
oauth = OAuth2Session(client=client)

# Register hook to avoid misleading error messages
oauth.register_compliance_hook("access_token_response", sentinelhub_compliance_hook)

# Fetch access token
token = oauth.fetch_token(
    token_url='https://services.sentinel-hub.com/auth/realms/main/protocol/openid-connect/token',
    client_secret=client_secret,
    include_client_id=True
)

# Make an authenticated request
resp = oauth.get("https://services.sentinel-hub.com/configuration/v1/wms/instances")
print(resp.content)

JavaScript with Axios
import axios from 'axios';
import qs from 'qs';

const client_id = '<client_id>';
const client_secret = '<secret>';

const instance = axios.create({
  baseURL: 'https://services.sentinel-hub.com',
});

const config = {
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded;charset=utf-8',
  },
};

const body = qs.stringify({
  client_id,
  client_secret,
  grant_type: 'client_credentials',
});

// All requests using this instance will have an access token automatically added
instance
  .post('/auth/realms/main/protocol/openid-connect/token', body, config)
  .then((resp) => {
    Object.assign(instance.defaults, {
      headers: { authorization: `Bearer ${resp.data.access_token}` },
    });
  });

OAuth2 Client Registration

Limitations with OAuth Client Registration

Interactive client registration has not yet been released. The only currently supported OAuth interactive client for developers is the Planet CLI and SDK for Python. To use this, you do not need to register your own client.

Client registration is only available for machine-to-machine (M2M) clients which utilize Sentinel Hub services (services.sentinel-hub.com), and not all services (for example, services hosted at api.planet.com).

Applications accessing Planet APIs on behalf of an end-user should be registered with the platform and obtain a unique client ID. This allows the end-user to manage which applications have access to their account independent of each other.

OAuth clients are managed under the OAuth Clients panel on your Account page.

Select Create New from the top right of the OAuth Clients list.
Enter a name for your client.
Set the expiration date. You can set the client credentials to never expire. For OAuth clients without expiration you will need to confirm your understanding of risks.
Choose whether the credentials will be used by a single page application (SPA). If yes, you will need to acknolwedge the risks.
If for a single page application, you can specifiy allowed web origins or choose to allow all doamins.
Select Create New Client
Securely store your client secret, as you will not be able to see it again after closing the dialog.

Create a new OAuth client.

API Key

Planet API keys provide access to the platform using a simple fixed string bearer key. API keys grant access to the platform equivalent to that of the key's owner, and should be protected as being as sensitive as the owner's password. If your API key is exposed, contact Planet Technical Support.

API Key Long-term Support

Planet intends to eventually deprecate API keys in favor of OAuth2 mechanisms. No specific timeframe has been set for deprecating API keys, but you should use OAuth2 mechanisms where possible.

Today, that means that if you are interacting with the Planet CLI and SDK for Python, we recommend using the Authorization Code Grant workflow instead of using an API key.

API Key Compatibility

Planet API keys will work for Planet APIs underneath api.planet.com, but will not work for APIs on services.sentinel-hub.com. There is no plan for API keys to ever be supported by APIs underneath services.sentinel-hub.com.

Obtaining Your API Key

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.

Deprecation Notice

Version 1 and Version 2 of the SDK allowed for API keys to be retrieved using the CLI's planet auth init command, or by calling SDK Python functions and providing a username and password. This has been deprecated in version 3 of the SDK. The SDK and the CLI still support API key authentication, but you must obtain the API key through the account application.

Using Planet API Keys

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.
```
Authorization: api-key <api_key>
```
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. Where supported, the URL query parameter has been implemented 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.

note

For the following examples, see SDK Configuration for details on environmental factors that may impact SDK and CLI behavior in these examples.

Python SDK and CLI

The Planet SDK and the CLI can be initialized to use a specific API key as follows:

CLI
Python SDK

Initialize the CLI to use the specifed API key

planet auth login --auth-api-key ${PL_API_KEY}

Use Planet SDK with a specific API key
import json
import planet


def example(pl_api_key):
    # Create an auth context with the specified API key
    plsdk_auth = planet.Auth.from_key(key=pl_api_key)

    # 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
    for item in pl.data.list_searches():
        print(json.dumps(item, indent=2, sort_keys=True))


if __name__ == "__main__":
    pl_api_key = input("API Key: ")
    example(pl_api_key)

HTTP Basic Auth

The SDK uses HTTP Basic when configured to use an API key. Once configured to use API Key based authentication, no additional steps are required.

CURL
CURL + CLI

Use API Key obtained from the your settings page with CURL
curl -u "${PL_API_KEY}:" https://api.planet.com/data/v1/searches

Use API Key initialized with SDK CLI with CURL
curl -u "`planet auth print-api-key`:" https://api.planet.com/data/v1/searches

`Authorization` Header

The SDK does not use the Authorization header to pass API keys. This method is only available when using CURL directly, or when the client uses their own HTTP client to make Planet API calls.

CURL
CURL + CLI

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

Use API Key initialized with SDK CLI with CURL
curl -H "Authorization: api-key `planet auth print-api-key`" https://api.planet.com/data/v1/searches

URL Parameter

The SDK does not use URL parameters to pass API keys. This method is only available when using CURL directly, or when the client uses their own HTTP client to make Planet API calls.

CURL
CURL + CLI

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}"

Use API Key initialized with SDK CLI with CURL
curl "https://api.planet.com/basemaps/v1/mosaics?api_key=`planet auth print-api-key`"

How the CLI and SDK Resolve Authentication Configuration

The Planet CLI and SDK for Python may load its configuration from a number of sources, depending on the runtime environment and how the SDK or CLI was invoked.

A number of environment variables and configuration files may impact the behavior of the SDK and the CLI in these examples. See the SDK Configuration documentation for details, including how to clear any previously configured settings.

Authentication Protocols​

Authentication Protocol Support​

OAuth2​

OAuth2 to Planet Entity Mapping​

OAuth2 Scopes​

OAuth2 Access Token Details​

Using OAuth2 Access Tokens​

Authorization Code Grant (Interactive User)​

Initializing with the Planet CLI and SDK for Python​

Client Credentials Grant (Machine-to-Machine)​

Sentinel Hub Authentication​

OAuth2 Client Registration​

API Key​

Obtaining Your API Key​

Using Planet API Keys​

Python SDK and CLI​

HTTP Basic Auth​

Authorization Header​

URL Parameter​

How the CLI and SDK Resolve Authentication Configuration​