Machine credentials are issued with scoped secrets or keys, rotated on schedule, revoked with bounded propagation enforcement, and audited separately from human user sessions.
Package status: AI-assisted reference package. Static package validation has passed; implementation scenarios remain not run and human domain review is required before stable adoption.
Decision
Model service accounts as non-human principals with hashed API keys or equivalent machine credentials, allow at most two overlapping active credentials during rotation, enforce revocation across API gateways and background workers within a bounded propagation window, and never treat machine credentials as interchangeable with browser sessions.
Scope
- Creation, display, rotation, expiry, and revocation of service account credentials.
- Scope binding, optional network constraints, and separation from human OAuth or session cookies.
- Cache behavior at validators and asynchronous propagation to workers.
- Audit trail for lifecycle events attributable to a human owner.
Outside this block
- Workload identity federation with cloud IAM roles unless mapped explicitly as credential type.
- Fine-grained authorization policy engines (see authorization blocks).
- Human MFA or passkey flows.
Contract
- Full credential secrets are shown only at creation or rotation issuance; persisted records store a one-way hash and a display prefix only.
- Each service account has a human owner responsible for rotation; orphaned accounts without owner are flagged and blocked from new credentials.
- At most the profile limit of active credentials may exist; rotation creates a successor before invalidating the predecessor after the overlap grace window.
- Revocation takes effect for new authentication attempts within the profile propagation bound across edge validators, internal services, and job runners.
- Expired or revoked credentials never downgrade to read-only; they fail closed.
- Authorization checks use credential scope independently of any user session; possessing a read-only key cannot invoke write APIs.
- Lifecycle events—create, rotate, revoke, auto-expire—append immutable audit entries with actor, target account, and credential prefix.
- Logs and support tools never contain complete secrets or reversible encodings.
Implementation guidance
- Use constant-time comparison against stored hashes; reject malformed keys before hash lookup to reduce timing leaks.
- Push revocation lists or version counters to shared caches with TTL no longer than the profile cache TTL.
- Map lifecycle states in
credential-states.yamlto rotation, overlap, and incomplete rotation handling. - Run nightly jobs for idle expiry and upcoming rotation reminders at 14 and 7 days before deadline.
- Integrate with secrets management for emergency break-glass credentials stored outside the application database.
Failure handling and safeguards
- If propagation lag exceeds the bound, alert and optionally widen failure mode to deny all keys for the affected account until consistent.
- If rotation fails mid-flight, keep the prior credential active and mark rotation as incomplete rather than leaving zero valid keys.
- If an owner departs, transfer ownership through admin workflow; do not auto-rotate secrets without notification.
- Compromise response revokes all credentials immediately and requires explicit reissuance after ticket approval.
Verification and operations
- Track age distribution, rotation compliance, revocation latency, and authentication failures by credential prefix.
- Test overlap and revocation with concurrent workers hitting APIs during rotation drills.
- Quarterly access review ties each active credential to a running service and owner on-call rotation.
Adoption assumptions
- Names and numeric values in
example.yamlare an adoption profile, not universal defaults. - Teams map scopes to their API surface and choose hash algorithms aligned with organizational standards.