Authentication

API-key surface (2026-05-18) — API keys authenticate the versioned /api/v1/* surface. 51 endpoints across 7 scope families are live today (Farms, Crops, Fields/Blocks/Plants, Tasks/Recurring/Templates, Crop Library, Analytics, Market Intelligence). Key minting is Summit-tier only. Remaining batches (AI, Billing, Team, User Profile) are queued — pages for those endpoints are noindexed until the routes ship. Track the API Reference for the current list.

API keys

WiseYield API keys are bearer tokens scoped to a single user and a set of capabilities. They are issued from the WiseYield dashboard and never round-trip through any other system.

Creating a key

Sign in to your WiseYield dashboard.
Open Settings → API Keys.
Click Create API Key.
Give it a descriptive name (e.g. “Production server”, “Mobile app”).
Choose Environment: live or test.
Pick the scopes the key needs (least-privilege).
Copy the key immediately — the full secret is shown once and never again.

Each user is limited to 10 active API keys at a time. Revoke unused keys before creating new ones.

Key format

wy_{environment}_{48_hex_chars}

Examples:

wy_live_a1b2c3d4e5f67890a1b2c3d4e5f67890a1b2c3d4e5f67890
wy_test_0f1e2d3c4b5a69870f1e2d3c4b5a69870f1e2d3c4b5a6987

Prefix: wy_ (identifies WiseYield).
Environment: live_ (production data) or test_ (test data).
Random: 48 hexadecimal characters (24 bytes from a cryptographic RNG).

Keys are stored as a SHA-256 hash. Once created, the cleartext value cannot be retrieved — only the prefix and a usage summary are visible in the dashboard.

Making authenticated requests

Send the API key in the Authorization header using the Bearer scheme:

const WISEYIELD_API_KEY = process.env.WISEYIELD_API_KEY;

const response = await fetch('https://www.wiseyield.co/api/v1/farms', {
  headers: {
    'Authorization': `Bearer ${WISEYIELD_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

Scopes

API keys carry a list of scopes. Requests are rejected with 403 Forbidden (INSUFFICIENT_SCOPE) when a key is missing the scope required by an endpoint.

Scope	Grants
`farms:read`	List and read farms
`farms:write`	Create, update, and delete farms
`crops:read`	List and read crops
`crops:write`	Create, update, and delete crops
`fields:read`	List and read fields, blocks, and per-plant records
`fields:write`	Create, update, and delete fields, blocks, and plants
`library:read`	Browse the crop library (admin catalog + own shortlist)
`library:write`	Add and remove crops from your shortlist
`market:read`	Read anonymized regional crop prices
`analytics:read`	Read analytics, predictions, and reports
`tasks:read`	List and read tasks
`tasks:write`	Create, update, and complete tasks
`team:read`	List farm members and invitations
`team:write`	Invite, update, and remove farm members
`webhooks:read`	List configured webhooks
`webhooks:write`	Create and update webhooks
`all`	Full access to every resource the user owns

Example: read-only integration

{
  "name": "BI Dashboard",
  "environment": "live",
  "scopes": ["farms:read", "crops:read", "analytics:read"]
}

Rate limits

Rate limits are applied per user, sliding-window, by subscription tier. The system fails closed: if the rate-limit backend is unreachable in production, requests are denied.

Tier	Limit
Expired trial	3 requests/hour
Seed	25 requests/hour
Sprout	50 requests/hour
Trial / Harvest	100 requests/hour
Grove	200 requests/hour
Summit	1,000 requests/hour

A 14-day trial grants Harvest-level access. Billing currency is auto-detected per the buyer’s country at checkout (EUR-denominated, via Dodo Adaptive Currency).

Rate-limit headers

Every response (success or rate-limited) carries the current window state:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 2026-05-17T14:00:00.000Z

X-RateLimit-Limit — total requests allowed in the current window.
X-RateLimit-Remaining — requests remaining before the limit kicks in.
X-RateLimit-Reset — ISO 8601 timestamp when the sliding window opens again.

When you hit the limit

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 2026-05-17T14:00:00.000Z

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED"
}

Implement exponential backoff or schedule retries against X-RateLimit-Reset:

async function fetchWithBackoff(url, init, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(url, init);
    if (response.status !== 429) return response;

    const resetIso = response.headers.get('X-RateLimit-Reset');
    const waitMs = resetIso
      ? Math.max(0, new Date(resetIso).getTime() - Date.now())
      : 2 ** attempt * 1000;
    await new Promise(r => setTimeout(r, waitMs));
  }
  throw new Error('Max retries exceeded');
}

Error responses

Authentication and authorization errors share a common shape:

{
  "error": "Unauthorized",
  "message": "Invalid or revoked API key",
  "code": "INVALID_API_KEY"
}

Status	`code`	Meaning
401	`MISSING_API_KEY`	No `Authorization` header sent
401	`INVALID_AUTH_FORMAT`	Header is not `Bearer <key>`
401	`INVALID_API_KEY_FORMAT`	Key doesn’t match `wy_(live\|test)_[a-f0-9]{48}`
401	`INVALID_API_KEY`	Key not found or has been revoked
401	`INACTIVE_API_KEY`	Key exists but is currently disabled
401	`EXPIRED_API_KEY`	Key passed its `expiresAt` timestamp
403	`IP_NOT_WHITELISTED`	Request came from an IP not in the key’s allowlist
403	`INSUFFICIENT_SCOPE`	Key is valid but missing the scope this route requires
429	`RATE_LIMIT_EXCEEDED`	Per-user rate limit reached

Security best practices

Store keys securely

Never hard-code keys. Use environment variables or a secrets manager.

# .env (add to .gitignore)
WISEYIELD_API_KEY=wy_live_...

Separate keys per environment

Use distinct keys for development, staging, and production. Scope them tightly and rotate them independently.

Restrict by IP when possible

When creating a key you can set an IP allowlist in metadata.ipWhitelist. Requests from any other origin return 403 IP_NOT_WHITELISTED.

Rotate on a schedule

Rotate keys at least every 90 days, and immediately when:

Someone with access leaves the team
A key may have been exposed (logs, repos, screenshots)
Compliance requires it

Monitor usage

The dashboard shows last-used timestamp, request volume, and error rate per key. Investigate unfamiliar patterns or sudden spikes.

Revoking a key

If a key is compromised or no longer needed:

Go to Settings → API Keys.
Find the key by name or prefix.
Click Revoke.

Revoked keys are invalidated immediately. Any client still presenting the key will start receiving 401 INVALID_API_KEY.

Get Started

Guides

API keys

Creating a key

Key format

Making authenticated requests

Scopes

Example: read-only integration

Rate limits

Rate-limit headers

When you hit the limit

Error responses

Security best practices

Revoking a key

Next steps

Quickstart

API Reference

Get Started

Guides

Documentation Index

​API keys

​Creating a key

​Key format

​Making authenticated requests

​Scopes

​Example: read-only integration

​Rate limits

​Rate-limit headers

​When you hit the limit

​Error responses

​Security best practices

​Revoking a key

​Next steps

Quickstart

API Reference

API keys

Creating a key

Key format

Making authenticated requests

Scopes

Example: read-only integration

Rate limits

Rate-limit headers

When you hit the limit

Error responses

Security best practices

Revoking a key

Next steps