Authentication

The SCO2-API uses OAuth2 Authentication and requires that you have an access token. In essence, this is a piece of information you add to your requests so the server knows it's you. These tokens do not last forever for a multitude of reasons, but you can get new ones and when they expire from the SCO2-API OAuth2 server at the token endpoint listed below.

How to use tokens

Once you have a token, do use it for authenticating all your requests within its validity period. While tokens do not last forever, they do last a reasonable amount of time, and sufficiently long that they can be reused. The information of how long each token lasts is embedded in the token itself in the exp claim, and can be read from there.

Do not fetch a new token for each API request you make. Token requests are rate limited, so if you are getting an HTTP 429 error, that means you are requesting too many tokens. Tokens are JSON Web Tokens (JWT), more information about them here.

Where to find the tokens

To consult your token, open the "Account" tab in your dashboard. It should show an "API Authentication Token" under the User Credentials panel.

If you use the dashboard to interact with the API, the token is automatically used by the requests performed by the front-end. If you plan to make your own API requests using the API docs, you can copy the token value and paste it locally and insert it into your requests to the API.

If you plan to create the API requests programmatically, the token should be inserted as part of the Authorization header to the request, preceded by the mention Bearer. Here is an example of how the headers payload would look like for a GET request:

headers = {
    'Authorization': "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImQxNjg5NDE1ZWMyM2EzMzdlMmJiYWE1ZTNlNjhiNjZkYzk5MzY4ODQiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vZXBvY2gtZnJvbnRlbmQtYXBwIiwiYXVkIjoiZXBvY2gtZnJvbnRlbmQtYXBwIiwiYXV0aF90aW1lIjoxNzA0ODc5NjMyLCJ1c2VyX2lkIjoiMWdtVUpFc3I5MVRrSnpRREFLYzVjZDNmeTBEMiIsInN1YiI6IjFnbVVKRXNyOTFUa0p6UURBS2M1Y2QzZnkwRDIiLCJpYXQiOjE3MDQ5OTE2MjIsImV4cCI6MTcwNDk5NTIyMiwiZW1haWwiOiJ3LnNpbW9uc2VAYXdheTRhZnJpY2EubmwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImZpcmViYXNlIjp7ImlkZW50aXRpZXMiOnsiZW1haWwiOlsidy5zaW1vbnNlQGF3YXk0YWZyaWNhLm5sIl19LCJzaWduX2luX3Byb3ZpZGVyIjoicGFzc3dvcmQifX0.k-0ayv8RDOZc6sfXN4lVOlTT-QJeZv0nbHy8wAjkjV6rXrEvmy9jW74sRyieXDD7jKZFMJTdRT7lV_d9Hk9BXF9Nrz9nZQNlGEHw1M0X6Tb4hT5RULuovACGaqLilT3AovYqoSZKCTLEFtXI7fF5bvqLIYfRSnS7g05h7J6qPpQn039ec8I-enUGlwckK-qATfNXKvKOCkfCHYrEpTwSJEQom191sIr5Cu_yq3VB8VESayl9qlG2ECOuLzIvZRURkKX0DFqmnLdMRCMRK_bI6arVlh6l4i0d0R1DAnhZjtk641MiPcOgx4IisIZqBY9hFI-5DHaEzgtOJfmjZ29WuA",
    'accept': 'application/json'
}

And for a POST request:

headers = {
    'Authorization': "Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6ImQxNjg5NDE1ZWMyM2EzMzdlMmJiYWE1ZTNlNjhiNjZkYzk5MzY4ODQiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL3NlY3VyZXRva2VuLmdvb2dsZS5jb20vZXBvY2gtZnJvbnRlbmQtYXBwIiwiYXVkIjoiZXBvY2gtZnJvbnRlbmQtYXBwIiwiYXV0aF90aW1lIjoxNzA0ODc5NjMyLCJ1c2VyX2lkIjoiMWdtVUpFc3I5MVRrSnpRREFLYzVjZDNmeTBEMiIsInN1YiI6IjFnbVVKRXNyOTFUa0p6UURBS2M1Y2QzZnkwRDIiLCJpYXQiOjE3MDQ5OTE2MjIsImV4cCI6MTcwNDk5NTIyMiwiZW1haWwiOiJ3LnNpbW9uc2VAYXdheTRhZnJpY2EubmwiLCJlbWFpbF92ZXJpZmllZCI6ZmFsc2UsImZpcmViYXNlIjp7ImlkZW50aXRpZXMiOnsiZW1haWwiOlsidy5zaW1vbnNlQGF3YXk0YWZyaWNhLm5sIl19LCJzaWduX2luX3Byb3ZpZGVyIjoicGFzc3dvcmQifX0.k-0ayv8RDOZc6sfXN4lVOlTT-QJeZv0nbHy8wAjkjV6rXrEvmy9jW74sRyieXDD7jKZFMJTdRT7lV_d9Hk9BXF9Nrz9nZQNlGEHw1M0X6Tb4hT5RULuovACGaqLilT3AovYqoSZKCTLEFtXI7fF5bvqLIYfRSnS7g05h7J6qPpQn039ec8I-enUGlwckK-qATfNXKvKOCkfCHYrEpTwSJEQom191sIr5Cu_yq3VB8VESayl9qlG2ECOuLzIvZRURkKX0DFqmnLdMRCMRK_bI6arVlh6l4i0d0R1DAnhZjtk641MiPcOgx4IisIZqBY9hFI-5DHaEzgtOJfmjZ29WuA",
    'accept': 'application/json',
    'Content-Type': 'application/json'
}

Token Generation Methods

There are two main ways to generate access tokens for programmatic API usage:

1. Email/Password Authentication (/refresh_token)

This method uses your email and password to generate a token. It's suitable for personal use or when you want to authenticate as yourself.

2. Client Credentials Authentication (/refresh_token_with_client_credentials)

This method uses client credentials (client_id and client_secret) for more secure, automated authentication. It's ideal for: - Server-to-server communication - Automated scripts and applications - When you want to avoid storing email/password credentials in your code - Better security practices for production environments

Email/Password Token Generation

For programmatic API users, being able to generate a token at the start of a session may be useful in order to avoid the manual step of copy-pasting the token.

A programmatic way of generating tokens is by providing your email and password to the /refresh_token endpoint.

Here's an example in python:

import requests

headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json'
}

request_data = {
    'email': "<user_email>",
    "password": "<user_password>"
}

TOKEN_RESPONSE = requests.get('https://epoch-sco2-api.com/refresh_token/', 
                              params=request_data, 
                              headers=headers)

headers['Authorization'] = f'Bearer {TOKEN_RESPONSE.json()["access_token"]}'

In javascript:

import axios from 'axios';

const headers = {
  'Accept': 'application/json',
  'Content-Type': 'application/json'
};

const request_data = {
  email: "<user_email>",
  password: "<user_password>"
};

axios.post('https://epoch-sco2-api.com/refresh_token/', request_data, { headers })
  .then(response => {
    const accessToken = response.data.access_token;
    headers.Authorization = `Bearer ${accessToken}`;

    // You can continue with other requests using the updated headers
    // For example:
    axios.get('https://epoch-sco2-api.com/deforestation_check/', { headers })
      .then(response => {
        // Handle the response
      })
      .catch(error => {
        // Handle errors
      });
  })
  .catch(error => {
    // Handle errors in refreshing token or other issues
  });

And using curl:

curl -X GET 'https://epoch-sco2-api.com/refresh_token/' \
-H 'accept: application/json' \
-H 'Content-Type: application/json' \
--data-urlencode 'email=<user_email>' \
--data-urlencode 'password=<user_password>'

Client Credentials Token Generation

For more secure, automated authentication, you can use client credentials. This method requires you to first register client credentials and then use them to generate tokens.

Step 1: Register Client Credentials

First, you need to register client credentials using your authenticated session:

import requests

# First, get a token using email/password
auth_headers = {
    'accept': 'application/json',
    'Content-Type': 'application/json'
}

auth_data = {
    'email': "<user_email>",
    "password": "<user_password>"
}

# Get initial token
token_response = requests.get('https://epoch-sco2-api.com/refresh_token/', 
                             params=auth_data, 
                             headers=auth_headers)
token = token_response.json()["access_token"]

# Use token to register client credentials
headers = {
    'Authorization': f'Bearer {token}',
    'accept': 'application/json',
    'Content-Type': 'application/json'
}

# Register client (optional: provide a name for easier management)
client_data = {
    "name": "my-automated-script"  # Optional, will use "default" if not provided
}

register_response = requests.post('https://epoch-sco2-api.com/clients/register', 
                                  json=client_data, 
                                  headers=headers)

credentials = register_response.json()
print(f"Client ID: {credentials['client_id']}")
print(f"Client Secret: {credentials['client_secret']}")

Step 2: Use Client Credentials for Token Generation

Once you have client credentials, you can use them to generate tokens without needing your email/password:

import requests
from requests.auth import HTTPBasicAuth

# Your client credentials (store these securely!)
CLIENT_ID = "your_client_id_here"
CLIENT_SECRET = "your_client_secret_here"

# Generate token using client credentials
token_response = requests.get(
    'https://epoch-sco2-api.com/refresh_token_with_client_credentials/',
    auth=HTTPBasicAuth(CLIENT_ID, CLIENT_SECRET),
    headers={'accept': 'application/json'}
)

if token_response.status_code == 200:
    access_token = token_response.json()["access_token"]

    # Use the token for API requests
    headers = {
        'Authorization': f'Bearer {access_token}',
        'accept': 'application/json'
    }

    # Example API call
    response = requests.get('https://epoch-sco2-api.com/deforestation_check/', headers=headers)
    print(response.json())
else:
    print(f"Failed to get token: {token_response.status_code}")

In javascript:

import axios from 'axios';

const CLIENT_ID = 'your_client_id_here';
const CLIENT_SECRET = 'your_client_secret_here';

// Create base64 encoded credentials
const credentials = btoa(`${CLIENT_ID}:${CLIENT_SECRET}`);

axios.get('https://epoch-sco2-api.com/refresh_token_with_client_credentials/', {
  headers: {
    'Accept': 'application/json',
    'Authorization': `Basic ${credentials}`
  }
})
.then(response => {
  const accessToken = response.data.access_token;

  // Use the token for API requests
  const apiHeaders = {
    'Authorization': `Bearer ${accessToken}`,
    'Accept': 'application/json'
  };

  // Example API call
  return axios.get('https://epoch-sco2-api.com/deforestation_check/', { headers: apiHeaders });
})
.then(response => {
  console.log(response.data);
})
.catch(error => {
  console.error('Authentication failed:', error.response?.data || error.message);
});

Using curl:

# Generate token using client credentials
curl -X GET 'https://epoch-sco2-api.com/refresh_token_with_client_credentials/' \
-H 'accept: application/json' \
-u 'your_client_id:your_client_secret'

# Use the token for API requests
curl -X GET 'https://epoch-sco2-api.com/deforestation_check/' \
-H 'accept: application/json' \
-H 'Authorization: Bearer YOUR_ACCESS_TOKEN_HERE'

Managing Client Credentials

You can manage your client credentials through the API:

import requests

# List all your client credentials
list_response = requests.get('https://epoch-sco2-api.com/clients/list', headers=headers)
clients = list_response.json()["clients"]

# Delete a specific client credential
delete_response = requests.delete(
    'https://epoch-sco2-api.com/clients/delete',
    params={"client_id": "your_client_id_here"},
    headers=headers
)

Security Best Practices

1. Never commit credentials to version control - Store client credentials in environment variables or secure secret management systems
2. Use client credentials for production - Prefer client credentials over email/password for automated systems
3. Rotate credentials regularly - Delete and recreate client credentials periodically
4. Limit credential scope - Only create credentials for the specific use case needed
5. Monitor usage - Regularly check your client credentials list and remove unused ones

Error Handling

Both authentication methods return appropriate HTTP status codes:

• 200 - Success, token generated
• 400 - Bad request (invalid parameters)
• 403 - Forbidden (invalid credentials)
• 422 - Validation error (missing required fields)
• 429 - Rate limited (too many token requests)
• 500 - Server error

Always handle these responses appropriately in your applications.