Documentation Index

Fetch the complete documentation index at: https://docs.dr.green/llms.txt

Use this file to discover all available pages before exploring further.

​

Keys (API Key Lifecycle)

Endpoint reference: ⚠️ JWT-auth required. The /keys endpoints are how a holder generates, lists, and revokes the API key pairs they hand to store builders. Store builders don’t call these directly — they consume the resulting (apiKey, secretKey) pair. This page documents the lifecycle so you understand how key rotation works and what to expect when a holder revokes a pair.

​

Endpoints

⚠️ All key endpoints require a JWT, not an API-key signature. A store builder cannot generate or revoke keys for a holder — only the holder can, via the DAPP UI (which holds the JWT).

​

Key lifecycle at a glance

Holder logs into DAPP UI (JWT obtained via /auth/dapp/signIn)
    │
    ▼
POST /keys  →  receives { apiKey, secretKey }
    │       (this is the ONLY time the secretKey is returned;
    │        if the holder loses it, they must generate a new pair)
    ▼
Hands { apiKey, secretKey } to store developer (out-of-band — encrypted email,
                                                  password manager share, etc.)
    │
    ▼
Store uses the pair on every /dapp/* request
    │
    ▼
PATCH /keys/delete  →  revokes the pair
    │       (subsequent requests using the pair return 401)
    ▼
Holder generates a new pair if needed and re-shares with store

​

POST /keys — generate a new pair

​

Request body

{
  "label": "Production WooCommerce Store"
}

​

Response

{
  "success": true,
  "statusCode": 201,
  "message": "Success",
  "data": {
    "id": "<key-uuid>",
    "label": "Production WooCommerce Store",
    "apiKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
    "secretKey": "LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0tLS0tCg...",
    "createdAt": "2026-05-10T12:00:00.000Z"
  }
}

​

What the holder must do with the pair

1. Copy both values. The DAPP UI will warn that secretKey is shown once.
2. Hand off via a secure channel. Encrypted email, 1Password share, or in-person. Never plain SMS or unsecured Slack.
3. The store stores the pair in their secrets manager — AWS Secrets Manager, GCP Secret Manager, HashiCorp Vault, or at minimum environment variables in a secure deploy pipeline.

​

Limit

​

GET /keys — list active pairs

​

Canonical payload (if reachable via API key — currently JWT-only)

​

Response

{
  "data": {
    "keys": [
      {
        "id": "<uuid>",
        "label": "Production WooCommerce Store",
        "apiKey": "LS0tLS1CRUdJTiBQVUJMSUMgS0VZLS0tLS0K...",
        "isActive": true,
        "createdAt": "2026-05-10T12:00:00.000Z",
        "lastUsedAt": "2026-05-10T15:32:11.428Z"
      }
    ]
  }
}

​

PATCH /keys/{id} — update a key

{
  "label": "Production WooCommerce Store (v2)"
}

​

PATCH /keys/delete — revoke (soft-delete)

​

Request body

{
  "ids": [
    "<key-uuid-1>",
    "<key-uuid-2>"
  ]
}

​

Response

🪲 Note the unusual REST shape. This is a PATCH to /keys/delete rather than a DELETE to /keys/{id} or DELETE /keys with a body. It’s a backend convention; just match it.

​

What happens after revocation

• All in-flight requests using the revoked pair return 401 "User is not authorized" (the DAPP guard rejects).
• The holder can re-issue a new pair at any time.
• There’s no notification to the store — your store will start seeing 401s unexpectedly. Build for this:

async function withKeyRotationHandling(fn: () => Promise<unknown>) {
  try {
    return await fn();
  } catch (e: any) {
    if (e.statusCode === 401 && e.message === 'User is not authorized') {
      // Likely revoked. Surface to ops, don't silently retry.
      await alertOps('Dr Green API key may have been revoked');
    }
    throw e;
  }
}

​

What store builders should know

​

Have a key-rotation runbook

• A key is suspected compromised
• An employee with access leaves
• The annual rotation date arrives

1. Holder logs into DAPP UI
2. Generates new pair → labels it clearly (<store-name> rotation 2026-Q2)
3. Updates secrets manager with new pair
4. Deploys / reloads store config
5. Verifies a few read calls succeed with new pair
6. Revokes the old pair via DAPP UI
7. Verifies old pair now returns 401 (sanity check)

​

Plan for sudden 401s

• Detect the rotation-flavored 401 (“User is not authorized” with otherwise-correct signing)
• Page your on-call
• Surface a clear “store temporarily disconnected from Dr Green” status to customers in flight

​

Never request the holder’s wallet credentials

​

See also

• Authentication — how the keys are used in every request
• Auth (Holder Sign-In) — how the holder gets the JWT that lets them generate keys
• 04-errors.md § 401 Unauthorized — diagnosing key-related 401s