Authentication using OAuth Personal Tokens

In order for any application to be able to consume the TreeSnap web services API, authorization tokens must be created and managed appropriately.

Table of Contents

• Creating New Authorization Tokens
• Authenticating using Tokens
• Refreshing Tokens

Creating New Authorization Tokens

Personal authorization tokens allow you to access your TreeSnap account and utilize the web services API with permissions to access to your own private data. To create new tokens, follow the steps below:

• Login to your account on treesnap.org
• Visit your developer dashboard treesnap.org/developer
• Scroll to the bottom and create new tokens by providing a name and clicking "Generate Tokens"
• 
• Personal authorization tokens consist of around 1071 characters and have a lifetime of 1 year (see Refreshing Tokens section below).
• Click the "show" link to see your new token

Please keep your authorization tokens secure!

Authenticating using Tokens

Once authorization tokens are created, they can be used to authenticate your application and be granted access to any private data that you'd normally have access to when visiting the site. To authenticate your application, you must provide a token in the HTTP Authorization Header of the request.

Authorization: Bearer YOUR-API-TOKEN

For example, using curl, you can authenticate as follows:

curl -H "Authorization: Bearer YOUR-API-TOKEN" \
        https://treesnap.org/web-services/v1/my-observations

An example using PHP with Guzzle

<?php
$accessToken = 'YOUR-API-TOKEN';
$client = new GuzzleHttp\Client();
$response = $client->request('GET', 'https://treesnap.org/web-services/v1/my-observations', [
    'headers' => [
        'Accept' => 'application/json',
        'Authorization' => 'Bearer '.$accessToken,
    ],
]);

Another example using Python with requests

import requests

token = 'YOUR-API-TOKEN'
headers = {'Authorization': 'Bearer ' + token}
url = 'https://treesnap.org/web-services/v1/my-observations'
r = requests.get(url, headers=headers)

Refreshing Tokens

All personal authentication tokens expire within a year of creation. Therefore, in order for your application to continue having access to an account, tokens must be refreshed before they expire. To do so, you may send a POST request to /web-services/v1/refresh-tokens while authenticated. See table below for required parameters. As this is a protected end-point, you must also include your token in the Authorization header as described in the section above.

URL	Type	Params	Response
/web-services/v1/refresh-tokens	POST	access_token Required. Current API token	*TokenResponse

^* see below for data structure

Example Response:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6IjYxNDhjMTJlMTU5ZTYxY2NhMzNlMmJjMDI2Zjc2ZTlmZWEzMDk1NTBkMWQzZjE0ZTQyYThhYjkzYzA0ODg1YzQxMTVjMDZlNGIzMWNhYjQ5In0.eyJhdWQiOiIxIiwianRpIjoiNjE0OGMxMmUxNTllNjFjY2EzM2UyYmMwMjZmNzZlOWZlYTMwOTU1MGQxZDNmMTRlNDJhOGFiOTNjMDQ4ODVjNDExNWMwNmU0YjMxY2FiNDkiLCJpYXQiOjE1MzA2NDYzMjksIm5iZiI6MTUzMDY0NjMyOSwiZXhwIjoxNTYyMTgyMzI5LCJzdWIiOiIxIiwic2NvcGVzIjpbXX0.v8m3QpzS6RslspYisjMjYY2hDtf_ns901pMahSDJQbLYOT4DKcOOHAL27n7epBg83qX8cMBm0tHz-81lBIDdnTLFwLqIl65Y9c4kR387QB1lvLKonsUrR13me4i29InrU9YrDd1rWTbpnKO6rHlIO5u7jnmZMKXI6EFL8ZLnjTCN7a0iQppTlHwpZ_fbHtTxjXz-C-1Rl0AMSM55RhxT3rrrH0H5q98YfHfNN63Ep6xvyk6n3sMHW70MdOMUPVdYJMXAJDrSioJ9rhd657gEyfIQkhKpw39o3hjYeM_M6Gew8W8U54bQMzSGhCQeNIeFWtr8W3dZgEFc7LXjGnEiQnHUn-4ge2_pSwUGkvkBs4k-gWAJck01FbLe5EiwJ5RBTUSMe0pM3Ctww9AOGPfDAMO8EWYhXD2HHmSEaX7CRlBYywNlT7-FF63gUlxp_EsKqelhno2-PlzDpW5WWF0wXNfkkTURSAyeOoLmGOIhdKJJk3fr4diKUTSAhax1beOnYGN91BkZVX2jbhrmq9k2TSeLxXQMtl3cMriWn_HDw_Elyw2gd0hv7aqVt5m6e5Z1GaWgh3_9Yax2Pcs6FbvTQJn5eS27vGdNIll703DKljRZ18WEgd5_BTY-dUtPzkOA3aiXAJrqBDSuB4xmaHe3ugX2M8zi4L4aex0mGzM0KvE",
    "expires_at": {
        "date": "2019-07-03 19:32:09.000000",
        "timezone_type": 3,
        "timezone": "UTC"
    },
    "error_code": 0,
    "message": "Tokens updated successfully"
}

Data Structures

Name	Structure
TokenResponse	JSON { "access_token", "expires_at", "error_code", "message" }

Error Codes

Code	Reason
0	No errors occurred
1000	The provided access token does not exist.
1100	Tokens mismatch. Please use the same token in both the Authorization header and the access_token parameter.