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](#creating-new-authorization-tokens)
- [Authenticating using Tokens](#authenticating-using-tokens)
- [Refreshing 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](https://treesnap.org/login)
- Visit your developer dashboard [treesnap.org/developer](https://treesnap.org/developer)
- Scroll to the bottom and create new tokens by providing a name and clicking "Generate Tokens"
![Developer Dashboard](https://github.com/user-attachments/assets/e3acde97-8194-4566-b24f-5ba0d50f8a3a)
- Personal authorization tokens consist of around 1071 characters and have a lifetime of 1 year (see [Refreshing Tokens](#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](https://github.com/guzzle/guzzle)
```php
<?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](http://docs.python-requests.org/en/master/)
```python
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](#authenticating-using-tokens).

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

<sup>*</sup> see below for data structure

**Example Response:**

```json
{
    "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` <br>{<br>  "access_token",<br>  "expires_at",<br>  "error_code",<br>  "message"<br>}|

**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.|