Authentication and API keys

Every request to the API carries an organization API key in the X-API-Key header. A key belongs to one AgroSat organization and gives access only to the fields that organization registered through the API.

Get access

API access is part of a contract with AgroSat. Once AgroSat enables the API for your organization, the organization owner can create keys. There is no self-service sign-up.

Trial access works the same way: you get an ordinary key with a small unit quota and an expiry date. When the trial ends the key stops working.

Create a key

Only the organization owner sees the API section and can create keys.

1. Sign in to the AgroSat web app at app.agrosat.uz and open Settings.

2. In the API keys card, type a name that says where the key will be used, for example production or staging, and select Create.

3. Copy the key straight away. It starts with ags_ and is shown only once; AgroSat keeps only its prefix and a hash.

4. Store it in your secret manager or deployment environment, not in source code.

The card lists every key with its name, prefix, who created it, when and from which IP address, when it was last used and when it expires. The number of live keys is capped by your contract (2 by default). When you reach the cap, revoke a key before creating another.

Send the key

Put the key in the X-API-Key header of every request.

curl

curl https://api.agrosat.uz/v1/fields -H "X-API-Key: $AGROSAT_API_KEY"

Python

import os
import requests

session = requests.Session()
session.headers["X-API-Key"] = os.environ["AGROSAT_API_KEY"]
r = session.get("https://api.agrosat.uz/v1/fields", timeout=30)

JavaScript

const res = await fetch("https://api.agrosat.uz/v1/fields", {
  headers: { "X-API-Key": process.env.AGROSAT_API_KEY },
});

Header only

A key in the query string, such as ?api_key=…, is never accepted: the request fails with 401 invalid_api_key. Query strings end up in logs and browser history.

A request fails with 401 invalid_api_key when the key is missing, unknown, revoked or past its expiry, or when API access for the organization has been switched off or its contract has expired.

Rotate a key

Rotating means running two keys for a short time so nothing breaks:

1. Create a new key in Settings → API keys.

2. Deploy it to every service that calls the API.

3. Revoke the old key. Requests with it fail with 401 from the next request on.

If you are already at your key cap, revoke an unused key first, or ask AgroSat to raise the cap.

Revoke a key

Select the revoke icon next to the key in Settings → API keys and confirm. The key stops working immediately and cannot be restored. Revoke a key as soon as you suspect it has leaked.

Keep keys on your server

The API is meant for server-to-server calls. Browsers may call it only from https://docs.agrosat.uz; requests from any other web origin are refused by the browser. Never put a key into a web page, a mobile app or a public repository: anyone who extracts it can spend your units and hectares.

Next steps

Register fieldsSend field boundaries and manage them.

Rate limitsHow many requests a key may send per minute.

Usage in the portalWatch units, hectares and keys in the web app.