# Pathrule Pattern: API Keys and Service-to-Service Authentication (1.0.0)
# ::pathrule:package:api-keys-service-auth

### [RULE] Store only a verifier for API keys  (path: /src/auth)
<!-- scope: folder | priority: high | strict -->

An API key is a bearer secret. Storing it in plaintext means a database read becomes immediate access to every integration without an additional secret boundary.

- Generate key material with a cryptographically secure source and enough entropy to resist guessing independent of rate limiting.
- Use a non-secret public prefix or identifier to find the record and store the secret portion through an approved password-style hash or keyed verifier design.
- Compare verifiers through the library's safe function and return one generic authentication failure for unknown, expired, disabled, and incorrect values.
- Show the secret only at creation or rotation and require the caller to create a replacement when it is lost.

See /ops/credentials for the adjacent decision or procedure that completes this constraint.

---

### [RULE] Authorize keys by narrow service scope  (path: /src/api)
<!-- scope: folder | priority: high | strict -->

A key that means full account access becomes a permanent unattended administrator password. Machine credentials need permissions aligned to the integration's actual job.

- Represent the key as a dedicated service principal or integration identity rather than impersonating a human owner silently.
- Grant explicit operation and resource scopes and default new capabilities to unavailable until the key owner opts in.
- Separate development, staging, and production keys and reject a credential outside its environment or intended audience.
- Apply per-key and per-principal rate, quota, and anomaly controls without treating source IP as the sole authentication factor.

See /src/auth for the adjacent decision or procedure that completes this constraint.

---

### [RULE] Accept API keys only through protected transport and bounded logging  (path: /src/api)
<!-- scope: folder | priority: high | strict -->

Keys in query strings leak through browser history, referrers, proxies, access logs, dashboards, and copied URLs. Even headers can leak when generic request logging records them.

- Reject plaintext transport and accept the credential through the documented header or protocol field, not URLs or ordinary form data.
- Redact full key values and authorization headers at the earliest observability boundary and scan error and debug paths too.
- Log public key prefix or record identity, service principal, scope decision, operation, outcome, and source context for audit without retaining the secret.
- Prevent credentials from being accepted in browser-facing cross-origin contexts unless the integration and storage threat model explicitly supports that client.

See /ops/credentials for the adjacent decision or procedure that completes this constraint.

---

### [MEMORY] Rotation overlaps credentials and preserves attribution  (path: /ops/credentials)

Immediate replacement causes unattended clients to fail, while indefinite overlap leaves compromised credentials active. Rotation needs two distinguishable keys and observable use.

- Create a new key with the same or narrower principal and scopes and show its secret once through an authenticated owner workflow.
- Track last use and recent operation evidence separately for old and new key identities so the owner can prove migration.
- Set an overlap deadline, notify the owner, and revoke the old key after adoption or immediately when compromise requires it.
- Keep audit records after revocation according to policy and ensure caches and gateways stop accepting the old verifier promptly.

See /src/auth for the rule or workflow that puts this decision into practice.