Security model
Security
Treat API tokens as production secrets: minimize authority, preserve one-time delivery, plan immediate rotations, and rely on live identity checks.
Credential properties
The API token is a high-entropy random secret, not a user-chosen password. Its prefix and suffix make the credential recognizable and versioned without weakening its entropy.
Encoded as 43 base64url characters—256 bits of entropy.
Case-sensitive vou_…v1 parsing rejects malformed variants.
Only SHA-256 of the complete plaintext is indexed and retained.
^vou_([A-Za-z0-9_-]{43})\.v1$const secret = randomBytes(32).toString('base64url');
const token = `vou_${secret}.v1`;
const tokenHash = sha256(token);A slow password hash is unnecessary for a uniformly random 256-bit secret. The indexed SHA-256 digest enables direct lookup without making plaintext recoverable.
Storage and transport
Do
- Use a server-side secret manager.
- Inject through protected environment/configuration channels.
- Send only in the HTTPS bearer header.
- Give each integration its own credential.
- Redact headers in traces and error reporting.
Never
- Browser localStorage or sessionStorage.
- Frontend source code or public environment variables.
- URLs, query parameters, or analytics payloads.
- Logs, screenshots, issue reports, or chat messages.
- A shared token across staging and production.
Defense in depth on every request
This revalidation means a leaked token loses utility when its owner is suspended, role changes, merchant ownership changes, or the merchant becomes inactive—even if the stored token record itself was never edited.
Rotation and incident response
Identify the token record by safe metadata and understand its current scopes and consumers.
Rotate when the integration continues; revoke when it must stop. Old plaintext becomes invalid immediately.
Move the new one-time secret through your controlled secret-delivery process.
Confirm expected calls succeed and the prior credential receives 401.
Operational visibility and limits
lastUsedAt, bounded IP, and bounded user agent update at most once every five minutes.
Generation, rotation time, expiry, revocation time/reason, and timestamps remain visible.
There is no per-token request trail or API-token audit-event collection.
No per-token rate limit is added by this system. Existing global and route throttles continue to apply, but API.md does not publish numeric limits or rate-limit headers.