API Key Authentication
Acceso uses API keys for machine-to-machine authentication. Keys are validated at request entry. Failed authentication is rejected before any domain work.
What an API key represents
An API key identifies a single consumer. It carries enforcement metadata:
Plan tier and billing association.
Rate limits and quota configuration.
Enabled domains and endpoint categories.
Feature flags for staged rollouts.
Key status (active, suspended, revoked, expired).
How clients authenticate
Send the key on every request via headers. Validation is synchronous. It happens before any domain work.
Authorization: Bearer <YOUR_API_KEY>Some deployments also support an explicit key header (useful behind proxies that strip Authorization):
X-API-Key: <YOUR_API_KEY>Use exactly one authentication header per request. Sending multiple increases ambiguity and risk.
Validation behavior
Key must be present and well-formed.
Key must be active (not revoked, suspended, or expired).
Key must be allowed to access the requested API surface.
Rotation and environment separation
One key per environment (
dev,staging,prod).One key per integration boundary (per service, not per engineer).
Staged rotation:
Create new key.
Deploy new key.
Confirm traffic.
Revoke old key.
Rotation is supported without downtime. Multiple active keys per account are allowed.
Storage and logging guarantees
Key material is redacted in access logs.
Only a short fingerprint may be recorded for correlation.
Sensitive headers are excluded from telemetry payloads.
Keys are stored in hashed form. Plaintext keys are never persisted. They must never appear in logs.
Security best practices
Failures are rejected early. They return a structured error envelope. No internal services are invoked.
Store keys in a secret manager. Avoid
.envin production.Never ship keys to browsers or mobile apps.
Rotate immediately on suspected exposure.
Use scoped keys. Prefer least privilege over “one key for everything”.
Last updated