Supported API

A faster API with more consistent response formats can be found at https://api.inaturalist.org. You will still need to refer to the authentication documentation for obtaining an OAuth accesstoken.

Authentication

iNaturalist is an OAuth2 provider and supports the Authorization Code, Resource Owner Password Credentials, and Proof Key for Code Exchange (PKCE) flows, as well as some custom auth flows for 3rd party authentication. Methods marked Auth required require authentication via one of the aforementioned methods. Please make sure to use https://www.inaturalist.org as the base URL for authorization flows and for authenticated requests to ensure passwords and access tokens are encrypted. Unfortunately we must maintain the vanilla http endpoints for backward compatability, but all future API users should make requests with SSL. Note that many PUT and DELETE methods also check for ownership and will fail if you try to use them when not authenticated as the user who owns the associated resources.

Auth Examples

Before you make any authenticated requests, you'll need to create an iNat application. The redirect_uri should be functioning URL to which users will be redirected upon successfully authorizing your app with access to the user's iNat data.

There are plenty of language-specific OAuth2 libraries out there, so find one you like or get familiar enough with OAuth2 to construct requests and manage redirect flows yourself. The following examples use Ruby's oauth2 gem.

Authorization Code Flow

This is what you'll want to use if your app is a web app, and/or you're sure you're users can open a web browser for auth *and* you can store your client secret in a secure fashion. The rough outline is you redirect your user to iNat, the user is offered the choice to authorize your app with access to their iNat data, and if they agree, they are redirected to the redirect_uri you specified with an access_token in the params.

Proof Key for Code Exchange Flow

This is a variation on the Authorization Code Flow for use in situations where you cannot store your client secret securely, e.g. in a client-side Javascript application or a mobile application that could be decompiled. Instead of providing a secret to identify itself, the client provides a hashed, single-use "code verifier" when requesting an authorization code. When the client requests an access token it must provide the unhashed code verifier to verify that it is the same client that requested the authorization code. More details at the IETF, but the Doorkeeper docs might be easier to read.

Resource Owner Password Credentials Flow

Retrieve an access token based on the user's iNat username and password. This is more for desktop and mobile apps, or any situation where you can store a user's password and they have reason to trust you, i.e. not for web.

Assertion Flow

This is roughly based on http://tools.ietf.org/html/draft-ietf-oauth-assertions-01#section-6.3 and used to retrieve an access token for a user based on a 3rd party access token from Facebook or Google. It assumes the user is already a member of iNat or wants to be, and uses the 3rd party token to sign them up and / or authenticate them. It returns an access token without the authorization step. This method is only available to partners we're working with directly.

Deprecated API

Older, deprecated, API endpoints are documented here.