Key Management APICopy Anchor Link

Org admins and owners can manage API keys programmatically via the Keys API, the CLI (gridwonk keys), SDK methods, or the customer dashboard.

/api/v1/keys* endpoints require a management key. Runtime keys are denied key lifecycle operations.

GridWonk platform management keys can create a runtime key for another organization, or update a runtime key already in a target organization, by passing organizationId. The platform organization uses the canonical gridwonk type after the Batch 8 rename; the legacy gridboost label is no longer accepted. An update uses the target organization only to scope the lookup; it does not move a key between organizations. Tenant management keys cannot perform cross-organization key operations, and cross-organization create requests cannot mint management keys.

EndpointsCopy Anchor Link

• GET /api/v1/keys — List keys for the authenticated organization
• POST /api/v1/keys — Create a new key
• GET /api/v1/keys/{id} — Get key details
• PATCH /api/v1/keys/{id} — Update key properties
• DELETE /api/v1/keys/{id} — Permanently revoke a key

ApiKeyInfo Response SchemaCopy Anchor Link

Legacy gb_live_/gb_test_ keys are no longer accepted. Use a gw_live_... or gw_test_... key.

List KeysCopy Anchor Link

curl https://gridwonk.com/api/v1/keys \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Query parameters: status (active/suspended/revoked), limit (default 50, max 100), offset.

Response: { keys: ApiKeyInfo[], total: number }

Create an API Key through RESTCopy Anchor Link

Create a new API key with POST /api/v1/keys, authenticated by an existing management key. An organization owner or admin can create a runtime key for application requests or another management key for key lifecycle operations. A runtime key cannot create keys. If you do not yet have a management key, use the first-key setup in the CLI guide before calling this endpoint. Your organization's API Keys page creates runtime keys only.

curl -X POST https://gridwonk.com/api/v1/keys \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Partner Integration","environment":"live","keyRole":"runtime","rateLimitPerMinute":120,"monthlyCostLimitUsd":250}'

Response (201):

{
  "key": {
    "id": "...",
    "keyPrefix": "gw_live_...",
    "plaintext": "gw_live_...",
    "...": "..."
  },
  "warning": "Store this key securely. It will not be shown again."
}

The plaintext field is returned only at creation time. Store it securely.

Optional create fields include expiresAt, monthlyCostLimitUsd, and, for GridWonk platform management keys only, organizationId to create a runtime key for another organization. Endpoint restrictions are applied by PATCH, not by create.

Limit: Maximum 25 non-revoked keys per organization. Active and suspended keys both count toward the limit.

Update KeyCopy Anchor Link

curl -X PATCH https://gridwonk.com/api/v1/keys/{id} \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Renamed Key","status":"suspended","rateLimitPerMinute":30,"allowedEndpoints":["/api/v1/jobs*"],"monthlyCostLimitUsd":100}'

Updatable fields: name, status (active/suspended), rateLimitPerMinute, allowedEndpoints, and monthlyCostLimitUsd. A GridWonk platform management key can pass organizationId to update a runtime key already in that target organization; it cannot move the key to a different organization. Customer keys cannot target another organization.

Cannot change environment or set status to revoked (use DELETE).

Revoke KeyCopy Anchor Link

curl -X DELETE https://gridwonk.com/api/v1/keys/{id} \
  -H "Authorization: Bearer $GRIDBOOST_API_KEY"

Response: { id: "...", revoked: true }

Revocation is permanent. A key cannot revoke itself (self-revoke protection).

SDK UsageCopy Anchor Link

import { GridWonkClient } from '@gridwonk/sdk';

const client = new GridWonkClient({
  apiKey: process.env.GRIDBOOST_API_KEY!,
});

// List keys
const { keys, total } = await client.listKeys({ status: 'active' });

// Create a key
const { key, warning } = await client.createKey({
  name: 'CI/CD Pipeline',
  environment: 'test',
  keyRole: 'runtime',
  rateLimitPerMinute: 120,
});
console.log(key.plaintext); // Store securely!

// Revoke a key
await client.revokeKey(key.id);

CLI UsageCopy Anchor Link

The CLI defaults to the canonical GridWonk API origin:

gridwonk keys list --status active
gridwonk keys create --name "CI Key" --env test --role runtime --rpm 120
gridwonk keys create --name "Tenant Runtime" --target-org <org-id>
gridwonk keys get <id>
gridwonk keys update <id> --name "Renamed" --status suspended \
  --allowed-endpoints "/api/v1/jobs*,/api/v1/published-requirements" --cost-limit 250
gridwonk keys revoke <id>

Security ConsiderationsCopy Anchor Link

• Key role separation: Runtime keys cannot call /api/v1/keys*; only management keys can manage keys.
• Self-revoke protection: A key cannot delete itself to prevent accidental lockouts.
• Organization scoping: Keys can only see and manage other keys within the same organization.
• Platform-only cross-org operations: Only GridWonk platform management keys can target another organization, and cross-org create is runtime-key-only.