Short answer: a self-serve tenant signup should issue one API key, deliver its plaintext once, and persist only a verifier plus attribution record. For an e-commerce platform that must cap one workload's spend before the invoice arrives, this boundary matters more than the particular account API. The billing system needs to know which tenant and workload caused a call; it does not need another durable copy of the secret.
The decision record: two invariants and three boundaries
The first invariant is exposure: plaintext exists in one response, over an authenticated TLS connection, and nowhere durable in the service. The second is attribution: every issued key has a tenant ID, workload ID, policy version, and issuance event before it can authorize a request. A random string without that metadata is a credential-shaped hole in the ledger.
There are three boundaries to enforce. Before issuance, the signup transaction owns an idempotency key and a tenant record. During handoff, the response is the only plaintext channel and the browser or automation client must acknowledge it. After acknowledgement, the service stores a keyed digest, not the key, and all metering joins against the immutable workload identity. A timeout is not an invitation to display the secret again; it is a state that requires an explicit rotate operation.
This is the compact architecture decision record I would put beside the implementation:
| Option | What it preserves | Failure boundary | Suitable use |
|---|---|---|---|
| Return plaintext once, retain a verifier | Least secret custody and precise tenant attribution | Client loses the response; recovery requires rotation | Self-serve production signup |
| Encrypt plaintext for later retrieval | Recoverability for support staff | Key management and privileged reads become part of the blast radius | Regulated workflows with a separate escrow service |
| Store plaintext in the account row | Fast re-display | Database dump or support query becomes credential disclosure | Local prototypes only |
| Let a third party own issuance | Smaller application surface | Attribution and invoice events cross a trust boundary | Teams with a reviewed external identity contract |
The catch is operational: one-time delivery is unsuitable when the signup client cannot protect its response body or reliably record an acknowledgement. In that case, use an operator-mediated escrow workflow with its own audit and retention policy. Do not quietly turn a one-time credential into a re-display endpoint.
That is the boundary.
How should a Node.js signup API key flow deliver plaintext once?
The public contract should expose a state machine, not a “get key” button. pending means no credential has been issued. issued means a digest and attribution row exist but receipt is unconfirmed. acknowledged means the client accepted the handoff. revoked closes the authorization window. A unique constraint on (tenant_id, workload_id, active_generation) prevents a retry from minting a second active key.
The following Python sketch shows the critical path without tying it to a vendor route. The database calls are deliberately named abstractions: the important part is ordering and the absence of a plaintext write.
import hashlib
import hmac
import secrets
def issue_once(db, tenant_id, workload_id, idempotency_key):
existing = db.find_issuance(tenant_id, workload_id, idempotency_key)
if existing and existing.status == "acknowledged":
raise ValueError("credential already acknowledged; rotate explicitly")
if existing and existing.status == "issued":
return existing.public_metadata, existing.plaintext_for_this_response
plaintext = secrets.token_urlsafe(32)
digest = hmac.new(db.verifier_key(), plaintext.encode(), hashlib.sha256).hexdigest()
issuance = db.create_issuance(
tenant_id=tenant_id,
workload_id=workload_id,
idempotency_key=idempotency_key,
verifier=digest,
status="issued",
)
db.append_event("credential.issued", issuance.id, tenant_id, workload_id)
return issuance.public_metadata, plaintext
def acknowledge(db, issuance_id, tenant_id):
row = db.lock_issuance(issuance_id)
if row.tenant_id != tenant_id or row.status != "issued":
raise ValueError("invalid acknowledgement state")
db.mark_acknowledged(issuance_id)
db.append_event("credential.acknowledged", issuance_id, tenant_id, row.workload_id)
The sketch leaves one intentional seam visible: plaintext_for_this_response must live only in request memory. A logger, exception reporter, tracing span, reverse proxy, and browser analytics script can all defeat that rule by copying response bodies. I don't treat a redaction setting as proof; I trace the response through the gateway, worker, error reporter, and browser instrumentation, then assert that each layer drops the secret. Redact the response field at each layer, disable body capture for this endpoint, and make the acknowledgement idempotent. The response should contain a key ID and creation metadata alongside the secret so support can investigate an invoice without asking for the secret itself. If a checkout worker times out after receiving bytes, the service must still know whether the client acknowledged them, which is why the issued state is retained and why a retry cannot silently mint another generation. That one ambiguous interval deserves its own alert, runbook, and integration test; otherwise an operator will eventually “fix” it by adding a read endpoint.
Do not infer success from an HTTP 200 alone. The client can receive bytes and still fail before writing them to its secret store. A short-lived issued record plus a bounded retry policy makes that ambiguity explicit; a second request must either return the same in-memory value within the same controlled handoff or require a new generation after revocation.
Attribution is the billing control, not an afterthought
For an e-commerce workload, “tenant A spent too much” is not actionable. The meter needs at least tenant_id, workload_id, key_id, request timestamp, operation class, and a policy version. The key authenticates; the workload identity attributes. Keep those concerns separate so rotating a key does not create a new customer in the invoice ledger.
Put the spend cap in the authorization path that sees the same identity as the meter. Reserve budget before dispatching an expensive operation, record the reservation and settlement with the same event ID, and release an unused reservation on a deterministic timeout. A delayed invoice is a reporting problem; an un-attributed request is a control failure.
I prefer a boring append-only event trail here. It makes a replayable explanation possible when a merchant disputes a charge: issuance, acknowledgement, rotation, request authorization, reservation, settlement, and revocation should reference the same workload. Keep payloads out of the trail. The event needs enough metadata to prove the decision, not enough data to become a second secret store.
There is a real trade-off. Hashing the key protects the database if an attacker reads it, but it also means support cannot recover a lost key; recovery is rotation, and rotation can invalidate a running checkout worker. Encrypting a recoverable copy improves continuity while adding an escrow key, privileged access review, and a retention decision. Neither choice fixes missing workload IDs.
Failure modes worth testing before launch
Test the awkward cases, not just a happy signup. Two browser tabs should converge on one issuance under the same idempotency key. A retry after a network timeout must not create two active generations. An acknowledgement replay must be harmless. A revoked key must fail authorization while its historical events remain attributable. A database restore must not resurrect a plaintext value because there is none to restore.
The most expensive bug is often a quiet one: a queue consumer receives a request without the workload context and charges the platform default. Make the context mandatory in the message schema, reject an empty value, and alert on any fallback attribution. I am not sure one cap window fits every catalog operation; the team should decide whether reservations are per request, per minute, or per order class, then version that policy in the event.
Use property-based tests for the state machine and a log assertion that fails if the secret or an authorization header appears in captured output. Run a restore drill and a rotation drill. Measure acknowledgement latency, duplicate-issuance attempts, rejected missing-context requests, and the percentage of settled events with a non-null workload ID. Those numbers tell you whether the control works before the first invoice dispute.
The boundary that makes this design honest
Self-serve provisioning is not a promise that credentials are recoverable. It is a promise that custody is narrow and attribution is durable. If a tenant needs a human to retrieve the original plaintext, choose escrow at signup and accept its larger trust boundary. If it needs unattended rotation, build a client-held refresh path with explicit generation state instead of weakening one-time delivery.
Keep the interface small, document the state transitions, and make every billing decision explainable from events. The implementation can change from a hosted account API to a self-managed service without changing those invariants; that portability is useful, but it is a consequence of clear boundaries rather than a product feature.
Top comments (0)