API Key Management Capability Buildprint

This Capability Buildprint packages a guarded workflow for adding secure API key management to an existing SaaS or B2B app.

It is designed for coding agents. It is not a copy-paste auth tutorial.

What it adds

• API key generation with one-time secret display
• hash-only key storage with searchable key prefixes
• key scopes or permissions
• revocation and rotation/replacement flow
• request authentication middleware or helper
• audit events for key lifecycle and usage
• verification and receipt requirements

What the host app must already have

• authenticated user identity
• persistence layer or approved persistence decision
• server-side API route/action capability
• account, team, organization, or owner model for keys
• environment/config pattern when hashing parameters or secrets are configured

Execution profile

guarded

API keys grant programmatic access to host data and actions. The applying agent must assess the host, plan the graft, implement through phases, verify, and write a receipt.

Agent flow

flowchart TD
  A[Read BUILDPRINT.md] --> B[Read capability.yaml]
  B --> C[Check compatibility.md]
  C --> D[Write .buildprint/host-assessment.md]
  D --> E[Write .buildprint/capability-plan.md]
  E --> F[Contract and config]
  F --> G[Core integration]
  G --> H[Host wiring]
  H --> I[User/operator surface]
  I --> J[Verify]
  J --> K[Write .buildprint/capability-receipt.md]

Proof levels

flowchart LR
  A[structure] --> B[fixture]
  B --> C[runtime]

Use the highest honest level. Do not claim runtime proof without testing the host API surface.

Non-negotiables

• No source edits before host assessment and capability plan.
• No plaintext key storage.
• No recoverable secret after initial creation.
• No client-side-only API key validation.
• No access without owner/tenant boundary checks.
• No install success claim without valid, revoked, and wrong-scope proof.