1. Authentication

Most endpoints within the web service API require token-based authentication.

All requests are stateless, meaning that the API does not maintain sessions, and each web service call must be accompanied by appropriate authentication credentials, preferably in HTTP Headers (see below).

What kinds of 'users' can authenticate to the API?

Currently, there are various 'types' of users that authenticate to the API. From a usability point-of-view, all user types authenticate identically, but they must identify themselves accordingly. The user types are [currently] limited to:

• Guardians - guardian - These are autonomous devices, usually located in remote forests.
• Users - user - These are, generally, actual people who have logged-in to the API, and obtained a token.
• Registration Tokens - register - These tokens are for creating new accounts (user or guardian), and may be redeemed a specific number of times. These tokens are usually kept very short, so that they may be easily shared.
• Temporary Tokens - token - These tokens are for general use, and are not intended to persist for long. They are usually restricted (internally) to a certain number of uses and specific endpoints.

More info on the various attributes, quirks, limitations and advantages of each token type are explained later in this article.

Authentication Parameters

Authentication requests are defined by a three pieces of information:

• user_type: The "type" of user accessing the API (supported: guardian / user / token)
• user_guid: Unique identifier of the specified user
• token: A unique token, provided by (or certified by) the API at an earlier point in time

Authentication Methods:

HTTP Headers (preferred)

• x-auth-user: [user_type]/[user_guid]
• x-auth-token: [token]
• Example: x-auth-user: guardian/df72c626229f & x-auth-token: 5ffd69500c83b9d948f5d0852538b5b983453182

Query Parameters (supported, but not preferred)

• auth_user=[user_type]/[user_guid]
• auth_token=[token]
• Example: ?auth_user=guardian/df72c626229f&auth_token=5ffd69500c83b9d948f5d0852538b5b983453182

Field/Form Parameters (supported, but not preferred)

• auth_user=[user_type]/[user_guid]
• auth_token=[token]