AcreLens Authentication: API Key & OAuth 2.0 Guide (2026)

Authentication overview

AcreLens employs established authentication mechanisms to secure access to its Crop Health API, Yield Prediction API, Soil Moisture API, and Field Boundary API. These methods ensure that only authorized applications and users can interact with sensitive agricultural data and analytics. The choice of authentication method depends on the integration's specific requirements, such as the type of client application and the level of user interaction.

Integrating with AcreLens requires developers to obtain and manage credentials securely. All API requests to AcreLens must be made over HTTPS (TLS 1.2 or higher) to encrypt data in transit, protecting credentials and data from interception. Failure to authenticate requests properly typically results in 401 Unauthorized or 403 Forbidden HTTP status codes, as detailed in the AcreLens API reference documentation.

Supported authentication methods

AcreLens supports two primary authentication methods: API Keys and OAuth 2.0. Each method is designed for different use cases, offering varying levels of security and operational complexity.

API Keys

API Keys are the simplest form of authentication, suitable for server-to-server communication or applications where the API key can be securely stored and managed. An API Key is a unique string that identifies your application or user when making requests to AcreLens APIs. It grants access to the resources associated with your AcreLens account.

• How it works: The API Key is typically included in the Authorization header of HTTP requests, prefixed with Bearer, or as a query parameter for simpler integrations.
• When to use: Ideal for backend services, scripts, or internal tools where the API key can be kept confidential and not exposed to client-side code.
• Security consideration: API keys grant broad access; their compromise can lead to unauthorized use of your account's API quota and data. Regular rotation and restricted permissions are recommended.

OAuth 2.0

OAuth 2.0 is an industry-standard protocol for authorization that allows third-party applications to obtain limited access to an HTTP service, either on behalf of a resource owner (e.g., a user) or directly by the application itself. AcreLens implements OAuth 2.0 to support applications that need to access user-specific data without directly handling user credentials.

• How it works: OAuth 2.0 involves an authorization server (AcreLens) issuing access tokens to client applications after a user grants permission. The client then uses this access token to make requests to the resource server (AcreLens APIs) on behalf of the user. The OAuth 2.0 authorization framework defines several grant types, with AcreLens primarily supporting the Client Credentials grant for server applications and the Authorization Code grant for web and mobile applications.
• When to use: Recommended for public client applications (web, mobile) that need to access a user's AcreLens data, or for complex integrations requiring granular control over permissions and user consent.
• Security consideration: OAuth 2.0 tokens have a limited lifespan and can be refreshed, reducing the risk associated with long-lived credentials. Proper implementation requires secure handling of client secrets and redirect URIs.

Authentication methods comparison

The following table summarizes the key characteristics of AcreLens's supported authentication methods:

Getting your credentials

To begin authenticating with AcreLens, you need to obtain the appropriate credentials from your AcreLens developer account. Both API Keys and OAuth 2.0 client credentials (Client ID and Client Secret) are managed through the AcreLens Developer Dashboard.

For API Keys:

1. Sign up/Log in: Access the AcreLens Developer Dashboard by signing up for a new account or logging into an existing one.
2. Navigate to API Keys: In the dashboard, locate the "API Keys" section, typically found under "Settings" or "Credentials."
3. Generate Key: Click the "Generate New API Key" button. You may be prompted to provide a name for the key to help with organization and tracking.
4. Copy and store: Once generated, the API Key will be displayed. Copy it immediately and store it securely. AcreLens does not store API Keys in a recoverable format, so if you lose it, you will need to generate a new one.
5. Configure permissions (optional): Depending on your plan and specific needs, you might be able to assign specific permissions or scopes to your API key, limiting its access to only necessary API endpoints.

For OAuth 2.0 Client Credentials:

1. Register application: In the AcreLens Developer Dashboard, navigate to the "OAuth Applications" or "Integrations" section.
2. Create new application: Click to register a new application. You will typically need to provide an application name, description, and one or more Redirect URIs. The Redirect URI is crucial as it's where the user is redirected after granting authorization, and where the authorization code will be sent.
3. Obtain Client ID and Secret: Upon registration, AcreLens will issue a Client ID and Client Secret for your application. The Client ID is a public identifier, while the Client Secret must be kept confidential, similar to an API Key.
4. Securely store credentials: Record both the Client ID and Client Secret. Ensure the Client Secret is stored in a secure, non-public location.
5. Define scopes: During application registration or later configuration, you will define the necessary OAuth scopes your application requires (e.g., read:crop_data, write:field_boundaries). This allows users to understand and consent to the specific types of data your application will access.

Authenticated request example

This section provides a basic example of making an authenticated API call to an AcreLens endpoint using an API Key. For OAuth 2.0 examples, refer to the AcreLens authentication documentation on OAuth flows.

Using an API Key (Python example)

To authenticate with an API Key, include it in the Authorization header of your HTTP request, prefixed with Bearer. The following Python example demonstrates how to fetch crop health data for a specific field.

import requests
import os

# Your AcreLens API Key
# It's recommended to store your API key as an environment variable
ACRELENS_API_KEY = os.environ.get("ACRELENS_API_KEY")

if not ACRELENS_API_KEY:
    raise ValueError("ACRELENS_API_KEY environment variable not set.")

# Define the API endpoint and parameters
BASE_URL = "https://api.acrelens.com/v1"
FIELD_ID = "your_field_uuid_here"  # Replace with an actual field UUID
ENDPOINT = f"/fields/{FIELD_ID}/crop-health"

headers = {
    "Authorization": f"Bearer {ACRELENS_API_KEY}",
    "Content-Type": "application/json"
}

params = {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31"
}

try:
    response = requests.get(f"{BASE_URL}{ENDPOINT}", headers=headers, params=params)
    response.raise_for_status()  # Raise an HTTPError for bad responses (4xx or 5xx)

    crop_health_data = response.json()
    print("Crop Health Data:")
    print(crop_health_data)

except requests.exceptions.HTTPError as errh:
    print(f"Http Error: {errh}")
except requests.exceptions.ConnectionError as errc:
    print(f"Error Connecting: {errc}")
except requests.exceptions.Timeout as errt:
    print(f"Timeout Error: {errt}")
except requests.exceptions.RequestException as err:
    print(f"Something went wrong: {err}")

For JavaScript examples, refer to the AcreLens JavaScript SDK authentication guide.

Security best practices

Adhering to security best practices is essential when integrating with AcreLens APIs to protect your credentials and data. These practices apply regardless of the authentication method chosen.

Credential management

• Never hardcode credentials: Avoid embedding API Keys or Client Secrets directly in your source code. Use environment variables, secure configuration files, or secret management services (e.g., AWS Secrets Manager, Google Secret Manager) to retrieve them at runtime.
• Restrict access: Limit who has access to your API Keys and Client Secrets. Only authorized personnel should be able to view or modify them.
• Rotate credentials regularly: Periodically generate new API Keys and Client Secrets, and revoke old ones. This minimizes the risk associated with compromised credentials over time.
• Implement least privilege: Configure API Keys or OAuth applications with the minimum necessary permissions (scopes) required for your application's functionality. This limits the damage if credentials are compromised.

Secure communication

• Always use HTTPS: Ensure all communication with AcreLens APIs uses HTTPS (TLS 1.2 or higher) to encrypt data in transit. This prevents eavesdropping and tampering.
• Validate SSL certificates: Ensure your HTTP client is configured to validate SSL certificates to prevent man-in-the-middle attacks.

Error handling and logging

• Handle authentication errors gracefully: Implement robust error handling for 401 Unauthorized and 403 Forbidden responses. Avoid logging sensitive information related to authentication failures (e.g., API keys, full headers) to publicly accessible logs.
• Monitor API usage: Regularly monitor your API usage patterns for any anomalies that might indicate unauthorized access or compromise. AcreLens provides usage metrics in its Developer Dashboard.

Client-side security (for OAuth 2.0 web/mobile apps)

• Protect Redirect URIs: For OAuth 2.0, register only secure and specific Redirect URIs. Avoid using localhost or broad wildcards in production.
• Never expose Client Secrets: Client Secrets must never be embedded in client-side code (e.g., JavaScript in a browser or mobile app). They should only be used by secure backend services. Public clients should use PKCE (Proof Key for Code Exchange) with the Authorization Code grant type as recommended by RFC 7636 for OAuth 2.0.
• Secure token storage: Store access and refresh tokens securely on the client-side, avoiding local storage where possible for sensitive tokens. Consider using HTTP-only cookies or secure storage mechanisms provided by mobile operating systems.