Oauth¶

Summary¶

Classes

Functions

`build_authorize_url`(app_id, redirect_uri, ...)	Build the OAuth2 authorization URL.
`get_access_token`(username, password, app_id, ...)	Get an access token using the user's iNaturalist username and password, using the Resource Owner Password Credentials Flow.
`get_access_token_via_auth_code`(app_id, ...)	Get an access token using the OAuth2 Authorization Code flow, optionally with PKCE.
`get_keyring_credentials`()	Attempt to get iNaturalist credentials from the system keyring
`set_keyring_credentials`(username, password, ...)	Store iNaturalist credentials in the system keyring for future use.
`validate_token`(access_token)	Determine if an access token is valid

Module Contents¶

pyinaturalist.client.oauth.get_access_token(username, password, app_id, app_secret, jwt, refresh) → str¶

Get an access token using the user’s iNaturalist username and password, using the Resource Owner Password Credentials Flow. Requires registering an iNaturalist app.

Notes

API reference: https://www.inaturalist.org/pages/api+reference#auth
See Authentication for additional options for storing credentials.
This can be used to get either a JWT or OAuth token. These can be used interchangeably for many endpoints. JWT is preferred for newer endpoints.

Examples

With direct keyword arguments:

>>> from pyinaturalist import get_access_token
>>> access_token = get_access_token(
>>>     username='my_inaturalist_username',
>>>     password='my_inaturalist_password',
>>>     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
>>>     app_secret='bbce628be722bfe2abd5fc566ba83de4',
>>> )

With environment variables or keyring configured:

>>> access_token = get_access_token()

If you would like to run custom requests for endpoints not yet implemented in pyinaturalist, you can authenticate these requests by putting the token in your HTTP headers as follows:

>>> import requests
>>> requests.get(
>>>     'https://www.inaturalist.org/observations/1234',
>>>      headers={'Authorization': f'Bearer {access_token}'},
>>> )

Parameters:

username (str | None) – iNaturalist username (same as the one you use to login on inaturalist.org)
password (str | None) – iNaturalist password (same as the one you use to login on inaturalist.org)
app_id (str | None) – OAuth2 application ID
app_secret (str | None) – OAuth2 application secret
jwt (bool) – Return a JSON Web Token; otherwise return an OAuth2 access token.
refresh (bool) – Do not use any cached tokens, even if they are not expired

Raises:

requests.HTTPError –

if credentials are invalid

Return type:

str

pyinaturalist.client.oauth.get_access_token_via_auth_code(app_id, app_secret, use_pkce, use_oob, jwt, refresh, ...) → str¶

Get an access token using the OAuth2 Authorization Code flow, optionally with PKCE.

This is the recommended approach for CLI and desktop applications because users do not need to provide their iNaturalist password to third-party code. Instead, the user authenticates directly on inaturalist.org in their browser.

Notes

Requires registering an iNaturalist application at https://www.inaturalist.org/oauth/applications
When using PKCE (the default), no client secret is needed.
When using the local callback server, register your redirect URI as http://127.0.0.1:<port> (e.g., http://127.0.0.1:8080).
When using OOB mode, register your redirect URI as urn:ietf:wg:oauth:2.0:oob.

Examples

With PKCE (recommended, no client secret needed):

>>> from pyinaturalist import get_access_token_via_auth_code
>>> access_token = get_access_token_via_auth_code(
...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
... )

Without PKCE (requires client secret):

>>> access_token = get_access_token_via_auth_code(
...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
...     app_secret='bbce628be722bfe2abd5fc566ba83de4',
...     use_pkce=False,
... )

For headless/remote environments (OOB mode):

>>> access_token = get_access_token_via_auth_code(
...     app_id='33f27dc63bdf27f4ca6cd95dd9dcd5df',
...     use_oob=True,
... )

Parameters:

app_id (str | None) – OAuth2 application ID. Falls back to INAT_APP_ID env var or keyring.
app_secret (str | None) – OAuth2 application secret. Required when use_pkce=False.
use_pkce (bool) – Use PKCE (Proof Key for Code Exchange) instead of a client secret.
use_oob (bool) – Use out-of-band mode: the user manually copies the authorization code instead of using a local callback server. Useful for headless environments.
jwt (bool) – Return a JSON Web Token; otherwise return an OAuth2 access token.
refresh (bool) – Do not use any cached tokens, even if they are not expired.
port (int) – Port for the local callback server. Must match the redirect URI registered with your iNaturalist application.
timeout (int) – Seconds to wait for the user to complete authorization in the browser.
open_url (Callable[[str], None] | None) – Optional callback to open the authorization URL. Defaults to webbrowser.open. Useful for testing or custom browser handling.
get_code (Callable[[str], str] | None) – Optional callback for OOB mode that receives the authorization URL and returns the authorization code entered by the user. Defaults to input().

Raises:

.AuthenticationError – if credentials are missing, the user does not authorize in time, or the token exchange fails.

Return type:

str

pyinaturalist.client.oauth.get_keyring_credentials() → dict[str, str | None]¶

Attempt to get iNaturalist credentials from the system keyring

Return type:: dict[str, str | None]
Returns:: OAuth-compatible credentials dict

pyinaturalist.client.oauth.set_keyring_credentials(username, password, app_id, app_secret)¶

Store iNaturalist credentials in the system keyring for future use.

Parameters:

username (str) – iNaturalist username
password (str) – iNaturalist password
app_id (str) – iNaturalist application ID
app_secret (str) – iNaturalist application secret

pyinaturalist.client.oauth.validate_token(access_token) → bool¶

Determine if an access token is valid

Return type:: bool