Skip to main content
Every request to the AgriBackup API must include a valid API key. AgriBackup uses the X-API-Key header scheme — pass your key as a plain header value, or use the official SDKs which handle this automatically. There are no OAuth flows, no token expiry windows, and no refresh tokens to manage.

​
API key format

AgriBackup API keys are prefixed to indicate their environment:
PrefixEnvironmentDescription
sk_live_ProductionProcesses real compliance records, anchors on Hedera mainnet, and files to live TRACES NT
sk_test_SandboxFully isolated; no real blockchain transactions or EU system submissions
Generate and manage your keys from the developer console or programmatically via POST /api/v1/enterprise/api-keys.
A sk_live_ key has the authority to file binding legal records with the EU TRACES NT system and incur real Hedera consensus fees. Treat it with the same care as a production database password — never commit it to source control or expose it in client-side code.

​
Passing your API key

​
Raw HTTP

Include the key in the X-API-Key header on every request: 
curl -X POST https://live.agribackup.com/api/v1/enterprise/eudr/polygons \
  -H "X-API-Key: sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tx_unique_001" \
  -d '{"features": [...]}'
For sandbox requests, swap the base URL and key: 
curl -X POST https://sandbox.agribackup.com/api/v1/enterprise/eudr/polygons \
  -H "X-API-Key: sk_test_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tx_unique_001" \
  -d '{"features": [...]}'
Both X-API-Key and Authorization: Bearer header formats are accepted. The X-API-Key header is the canonical form used by all official SDKs.

​
Python SDK

import agribackup

configuration = agribackup.Configuration()
configuration.api_key['ApiKeyAuth'] = 'sk_live_YOUR_API_KEY'
# No need to set configuration.host — the SDK resolves it from the key prefix

with agribackup.ApiClient(configuration) as api_client:
    polygons_api = agribackup.EnterprisePolygonsApi(api_client)
    # ... make requests

​
Node.js SDK

import { AgriBackupClient } from '@agribackup/sdk';

const client = new AgriBackupClient({
  apiKey: 'sk_live_YOUR_API_KEY'
  // baseUrl is optional — omit it and the SDK resolves from key prefix
});

​
Java SDK

import com.agribackup.client.*;

ApiClient defaultClient = Configuration.getDefaultApiClient();
defaultClient.setApiKey("sk_live_YOUR_API_KEY");
// Do NOT call setBasePath — let the SDK resolve from the key prefix

​
Base URL auto-resolution

You do not need to configure a base URL when using an official SDK. The SDK inspects the sk_live_ or sk_test_ prefix and selects the correct host:
Key prefixResolved base URL
sk_live_https://live.agribackup.com
sk_test_https://sandbox.agribackup.com
If you call the API directly over HTTP (without an SDK), use the appropriate host from the table above. All paths are prefixed with /api/v1.
Switching your integration from sandbox to production requires changing only one string: the API key. Swap sk_test_… for sk_live_… and every endpoint URL resolves automatically.

​
Rate limits

The production environment enforces a limit of 100 requests per second per API key. Every response includes the following headers so you can monitor your usage in real time:
​
X-RateLimit-Limit
integer
The maximum number of requests permitted per rate-limit window.
​
X-RateLimit-Remaining
integer
The number of requests remaining in the current window.
​
X-RateLimit-Reset
integer
UTC epoch seconds at which the current window resets.
When you exceed the limit the API returns 429 Too Many Requests. Back off using the Retry-After header value before retrying.

​
Common authentication errors

​
401 Unauthorized

You receive 401 when no valid API key is present or the key is malformed. 
{
  "code": "UNAUTHORIZED",
  "message": "Missing or invalid API key",
  "details": []
}
Common causes:
  • The X-API-Key header is absent.
  • The key value is truncated or contains whitespace.
  • You are passing the key in the wrong header (e.g. Authorization: Token instead of X-API-Key).

​
403 Forbidden

You receive 403 when the key is valid but lacks the required scope for the requested operation. 
{
  "code": "FORBIDDEN",
  "message": "API key does not have the required scope",
  "details": []
}
Common causes:
  • The key was generated with restricted scopes (e.g. read-only) and you are attempting a write.
  • You are sending a sk_test_ key to the production host (live.agribackup.com) or vice versa.
  • The key has been rotated and the old value is being used.
Rotate keys with POST /api/v1/enterprise/api-keys/{keyId}/rotate.

​
Keeping keys secure

Follow these practices to keep your API keys secure:
  • Environment variables only. Load the key from an environment variable or a secrets manager (e.g. HashiCorp Vault, AWS Secrets Manager) — never hard-code it.
  • No client-side exposure. Never include a sk_live_ key in browser JavaScript, mobile app binaries, or any code that runs outside your trusted server environment.
  • Rotate regularly. Use POST /api/v1/enterprise/api-keys/{keyId}/rotate to issue a new key on a schedule or immediately after any suspected compromise.
  • Scope minimally. When creating keys for automated pipelines, grant only the scopes that pipeline requires.
  • Audit usage. List active keys with GET /api/v1/enterprise/api-keys and revoke any you no longer recognise.