Auth¶

Summary¶

Classes

Functions

`get_access_token`([username, password, ...])	Get an access token using the user's iNaturalist username and password, using the Resource Owner Password Credentials Flow.
`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.auth.get_access_token(username=None, password=None, app_id=None, app_secret=None, jwt=True, refresh=False)¶

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 (Optional[str]) – iNaturalist username (same as the one you use to login on inaturalist.org)
password (Optional[str]) – iNaturalist password (same as the one you use to login on inaturalist.org)
app_id (Optional[str]) – OAuth2 application ID
app_secret (Optional[str]) – 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.auth.get_keyring_credentials()¶

Attempt to get iNaturalist credentials from the system keyring

Return type:: Dict[str, Optional[str]]
Returns:: OAuth-compatible credentials dict

pyinaturalist.auth.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.auth.validate_token(access_token)¶

Determine if an access token is valid

Return type:: bool