Planet APIs live on two domains, and they don't accept the same credentials. APIs on api.planet.com accept API keys and OAuth user tokens. APIs on services.sentinel-hub.com accept only OAuth tokens. Using the wrong credential for the domain, or an OAuth token that has expired, is one of the most common causes of a 401 Unauthorized error. This article explains which credential to use for each domain and how to fix 401 errors.

API key: a fixed string that never expires. It gives the same access as its owner, so protect it like your password. You can have only one active API key at a time, and it's on your Account page under Settings.

OAuth user session: you sign in through a web browser, and your app receives short-lived access tokens that it refreshes as needed. This is Planet's preferred method for interactive use. The Planet CLI and Python SDK (version 3 and later) handle the sign-in and refreshing for you.

OAuth client (machine-to-machine): a client ID and client secret for automated processes that run without a person signing in. You create these under OAuth Clients on your Account page.
 

API key: yes.

OAuth user session: yes.

OAuth client (machine-to-machine): not yet. Planet is still working on this, so use an API key for automated workflows on api.planet.com for now.

 

API key: no. Planet has no plans to support API keys on this domain.

OAuth user session: yes.

OAuth client (machine-to-machine): yes.

 

On api.planet.com, send an API key in one of these ways (most APIs accept the first):

HTTP Basic authentication, with the API key as the username and an empty password.

An Authorization header in the form "Authorization: api-key <your key>".

An api_key query parameter in the URL. Tile streaming clients often use this method.

 

OAuth access tokens go in an Authorization header in the form "Authorization: Bearer <access token>", on either domain.

For a machine-to-machine client on services.sentinel-hub.com, request a token from this endpoint using your client ID and secret:

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

To use an API key with the CLI instead:

If you're upgrading from SDK version 1 or 2: the old planet auth init command, and signing in with a username and password to retrieve your key, no longer work in version 3. Copy your API key from your Account page instead.

A 401 means your authentication is missing or incorrect. Check these causes:

1. You're sending an API key to services.sentinel-hub.com. That domain only accepts OAuth tokens, so switch to an OAuth client or user session.

2. Your OAuth access token has expired. Tokens don't last forever, and the expiry time is in the token's exp claim. Refresh it, or let the Planet SDK refresh it for you.

3. The credential is in the wrong format. Check the header scheme: API keys use "api-key" and OAuth tokens use "Bearer". Also check that you haven't included extra spaces or quotation marks.

4. Your API key was reset. Only one key is active at a time, so a reset key stops working immediately. Copy the current key from your Account page.

5. Your OAuth client has expired. OAuth clients have an expiration date unless you chose "Never expire" when creating them. Create a new client if yours has expired.

A 401 is different from a 403 Forbidden. A 403 means Planet recognized you, but you don't have access to that resource. For example, it could be outside your plan, or your credit balance may have run out.

Reuse each access token until it's close to expiring. Planet throttles clients that request tokens too often, and token requests on services.sentinel-hub.com are rate-limited. Getting a 429 Too Many Requests error from the token endpoint means you're requesting tokens too often.