Skip to main content
GET

Endpoint

Dashboard-only endpoint. Authentication is via the WiseYield browser session (Clerk cookies). It cannot be called from a server-to-server integration today. Use the WiseYield dashboard’s Settings → API Keys page to manage keys; this page documents the wire format that page consumes.

Authentication

Requires a signed-in WiseYield session (Clerk cookies set by the dashboard). The cURL and Bearer examples below illustrate the wire shape but are not directly callable outside the browser — fetch('/api/api-keys', { credentials: 'include' }) from the dashboard is how it’s actually invoked.

Response

Returns list of API keys with usage statistics.
data
array
Array of API key objects (sorted by creation date, newest first)
total
number
Total number of active API keys

Errors

401
error
Unauthorized - User not signed in via Clerk
500
error
Internal Server Error - Failed to fetch API keys

How It Works

Query Flow:
  1. Authentication: Verifies user is signed in via Clerk
  2. Database Query: Fetches all API keys where:
    • userId matches authenticated user
    • revokedAt is null (not revoked)
  3. Sorting: Orders by createdAt descending (newest first)
  4. Security Masking: Masks full keys using maskApiKey() function
  5. Response: Returns array of masked keys with metadata
What’s Hidden: Full API key value is NEVER returned in list responses. Only the prefix and masked preview are shown. What’s Shown: All metadata (name, scopes, usage stats, expiration) is visible.

API Key Structure

Key Format

Components:
  • Prefix: wy_ (WiseYield identifier)
  • Environment: live or test
  • Random part: 48 hexadecimal characters (24 random bytes)

Environments

Available Scopes

Farm Management:
  • farms:read - View farms
  • farms:write - Create and update farms
Crop Management:
  • crops:read - View crops
  • crops:write - Create and update crops
Field Management:
  • fields:read - View fields
  • fields:write - Create and update fields
Analytics:
  • analytics:read - View analytics and predictions
Task Management:
  • tasks:read - View tasks
  • tasks:write - Create and update tasks
Team Management:
  • team:read - View team members
  • team:write - Manage team members
Webhooks:
  • webhooks:read - View webhooks
  • webhooks:write - Create and update webhooks
Full Access:
  • all - Full access to all resources

Use Cases

Display API Keys Table

Check Key Usage

Filter by Environment

Check for Expiring Keys

Best Practices

Regular Audits: Review API keys list monthly to remove unused keys.
Monitor Usage: Check usageCount and lastUsedAt to identify inactive keys.
Environment Separation: Use test keys for development, live keys only in production.
Scope Principle: Grant minimum scopes needed for each use case.
Full Keys Never Shown: The complete API key is only shown once during creation. Save it securely.
Revoked Keys Excluded: This endpoint only returns active keys (revokedAt = null).
10 Key Limit: Each user can have maximum 10 active API keys. Revoke unused ones.

Security Considerations

Key Storage:
  • Only SHA-256 hash stored in database
  • Prefix stored for identification (first 16 chars)
  • Full key never retrievable after creation
Display Safety:
  • Keys masked in UI: wy_live_abc123de...****
  • Prevents accidental exposure in screenshots
  • Safe to display in logs and monitoring
Scope Isolation:
  • Keys cannot access resources outside their scopes
  • all scope grants full access (use cautiously)
  • Scopes validated on every API request