API Keys and Service-to-Service Authentication

Pathrule3 Rules • 1 Memory

API keys identify software rather than a human session, so issuance, one-time display, storage, lookup, comparison, scope, environment, network context, rotation, expiration, audit, and compromise response must be designed as a credential lifecycle. This pattern constrains key storage, scope, and transport while recording machine-identity semantics for service and customer integrations. It differs from user authentication and enterprise SSO because keys represent applications, jobs, devices, or integrations and often run unattended for long periods.

Suggested path map

Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.

/ workspace root

src/

auth/

Store only a verifier for API keys

api/

Authorize keys by narrow service scope

Accept API keys only through protected transport and bounded logging

ops/

credentials/

Rotation overlaps credentials and preserves attribution

Rules

Store only a verifier for API keys/src/authhighstrictGenerate high-entropy credentials, display the secret once, and retain a prefix plus cryptographic verifier for lookup and comparison.

1	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.
2
3	- Generate key material with a cryptographically secure source and enough entropy to resist guessing independent of rate limiting.
4	- 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.
5	- Compare verifiers through the library's safe function and return one generic authentication failure for unknown, expired, disabled, and incorrect values.
6	- Show the secret only at creation or rotation and require the caller to create a replacement when it is lost.
7
8	See /ops/credentials for the adjacent decision or procedure that completes this constraint.

Authorize keys by narrow service scope/src/apihighstrictBind each credential to one principal, environment, allowed operations, resources, and optional network or workload constraints.

1	A key that means full account access becomes a permanent unattended administrator password. Machine credentials need permissions aligned to the integration's actual job.
2
3	- Represent the key as a dedicated service principal or integration identity rather than impersonating a human owner silently.
4	- Grant explicit operation and resource scopes and default new capabilities to unavailable until the key owner opts in.
5	- Separate development, staging, and production keys and reject a credential outside its environment or intended audience.
6	- Apply per-key and per-principal rate, quota, and anomaly controls without treating source IP as the sole authentication factor.
7
8	See /src/auth for the adjacent decision or procedure that completes this constraint.

Accept API keys only through protected transport and bounded logging/src/apihighstrictRequire HTTPS, use a dedicated authorization header, and redact credentials from logs, traces, errors, analytics, and support artifacts.

1	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.
2
3	- Reject plaintext transport and accept the credential through the documented header or protocol field, not URLs or ordinary form data.
4	- Redact full key values and authorization headers at the earliest observability boundary and scan error and debug paths too.
5	- Log public key prefix or record identity, service principal, scope decision, operation, outcome, and source context for audit without retaining the secret.
6	- Prevent credentials from being accepted in browser-facing cross-origin contexts unless the integration and storage threat model explicitly supports that client.
7
8	See /ops/credentials for the adjacent decision or procedure that completes this constraint.

Memories

Rotation overlaps credentials and preserves attribution/ops/credentialsIssue a replacement beside the old key, identify adoption, then revoke the prior key after a bounded migration window.

1	Immediate replacement causes unattended clients to fail, while indefinite overlap leaves compromised credentials active. Rotation needs two distinguishable keys and observable use.
2
3	- Create a new key with the same or narrower principal and scopes and show its secret once through an authenticated owner workflow.
4	- Track last use and recent operation evidence separately for old and new key identities so the owner can prove migration.
5	- Set an overlap deadline, notify the owner, and revoke the old key after adoption or immediately when compromise requires it.
6	- Keep audit records after revocation according to policy and ensure caches and gateways stop accepting the old verifier promptly.
7
8	See /src/auth for the rule or workflow that puts this decision into practice.

Why this pattern

AI agents often store plaintext keys, put them in query strings, grant account-wide authority, or rotate by invalidating the old credential before dependents can move.

Built for Platform teams authenticating customer integrations, internal services, automation, devices, or command-line clients.

Keeps your assistant from:

Recovering every active API key from a database breach
Leaking credentials through URLs and access logs
Using one production key across several unrelated services
Causing outage during an uncoordinated key rotation

View as markdown

License: Apache-2.0
Version: 1.0.0
Updated: 2026-08-25