Skip to content

Spec Authentication and Authorisation

mavrovde edited this page Nov 1, 2026 · 1 revision

Spec: Authentication and Authorisation

Part of the Technical Specification. Requirement prefix: SEC. This page makes Security and Access Keys normative; where the two differ, this page governs and the other is corrected.

1. Key format

vf_live_<keyId>_<secret><checksum>
vf_test_<keyId>_<secret><checksum>
Part Format
Prefix vf_live_ (production) or vf_test_ (sandbox), configurable (auth.key_prefix_live, auth.key_prefix_test)
keyId 10 characters base62, public, unique
secret 32 bytes from a cryptographically secure random generator, base62-encoded (43 characters)
checksum 6 characters base62 of CRC-32 over everything before it

The fixed prefix plus checksum lets secret scanners (including the code host's push protection, with a custom pattern) detect leaked keys with almost no false positives, and lets the service reject typos without a store lookup.

2. Presenting a key

ID Requirement Verification
SEC-001 Keyed operations MUST accept the key as Authorization: Bearer <key> (RFC 6750 section 2.1) and SHOULD accept X-API-Key: <key>. Handler
SEC-002 A key in the query string or in a form body MUST be refused with 400 key-in-query, MUST NOT be checked, and the service SHOULD flag the key id for the operator as exposed. Security
SEC-003 The key check MUST verify format and checksum first, then look up the key id, then compare the MAC of the secret in constant time. Unknown id, bad checksum and wrong secret MUST produce the same 401 invalid-key answer with indistinguishable timing within measurement noise. Security
SEC-004 A vf_test_ key MUST NOT be accepted by the production instance, and a vf_live_ key MUST NOT be accepted by the sandbox. Handler

3. Storage of keys

ID Requirement Verification
SEC-010 Only a MAC of the secret MUST be stored: HMAC-SHA-256 keyed with a server-side pepper held outside the access store. The secret and the MAC MUST never be logged or returned after issue. Security
SEC-011 Pepper rotation MUST be possible with a previous pepper configured; a key matching under the previous pepper MUST be re-MACed under the current one on first use. Unit
SEC-012 The full key MUST be shown exactly once, at issue, and MUST NOT be recoverable afterwards by anyone, including the operator. Review

4. Plans, scopes, tiers and use classes

Concept Values Decides
Scope places, roads, energy, parking, transit, accessibility, weather, rules, history Which operations a key may call
Tier critical, standard, bulk Priority under load ([[Spec: Rate Limiting and Quotas
Use class consumer, non_commercial, commercial Which source families a licence permits
Source families per plan Which data may be read
Limits rate, burst, daily and monthly quota, maximum page size, history depth Consumption
ID Requirement Verification
SEC-020 Every operation MUST declare exactly one required scope (two for history: roads and history); a key without it MUST receive 403 scope-denied. Contract
SEC-021 Plans MUST be data in the access store, changeable without a deployment; configuration only seeds defaults (plans.seed). Review
SEC-022 A key MUST belong to exactly one plan at a time; a plan change MUST take effect within auth.key_cache_ttl. Unit

5. The licence gate

ID Requirement Verification
SEC-030 A source family MUST be readable for a request only if it is in the key's plan, the plan's use class is permitted by the family's licence terms, any required terms acceptance is recorded for the key, and the family is not disabled (sources.disabled). The default is deny. Unit
SEC-031 The allowed set MUST be applied inside the storage read, so that a forbidden item is never read. Mapping
SEC-032 Every returned item MUST be checked again against the allowed set; a violation MUST abort the response with 500 internal, increment an alerting metric and never be served. Security
SEC-033 When some but not all answering families are permitted, the answer MUST contain only the permitted ones and carry the partial warning; 403 source-not-permitted MUST be used only when none is permitted. Handler
SEC-034 Terms acceptance MUST be recorded per key with the terms version and the instant; a new terms version MUST require new acceptance. Unit

6. Key lifecycle

stateDiagram-v2
  [*] --> Active: issue
  Active --> Rotating: rotate
  Rotating --> Active: overlap window ends, old secret invalid
  Active --> Expired: expiry reached
  Rotating --> Expired: expiry reached
  Active --> Revoked: revoke
  Rotating --> Revoked: revoke
  Expired --> [*]
  Revoked --> [*]
Loading
ID Requirement Verification
SEC-040 Issue MUST take a plan, a label, an owner contact and an optional expiry (default auth.default_expiry, design 365 days, at most 1 095 days). Unit
SEC-041 Rotate MUST issue a new secret under the same key id; the previous secret MUST stay valid for auth.rotation_overlap (design 7 days, at most 30) and then become invalid. Unit
SEC-042 Revoke MUST take a reason and MUST take effect on every instance within auth.revocation_propagation (design 5 s), and at the latest after auth.key_cache_ttl. Load
SEC-043 The service SHOULD warn a key holder of an approaching expiry by meta.warnings[] code key_expiring during the last auth.expiry_warning_days (design 14). Handler
SEC-044 Every lifecycle action MUST write an audit record in the same transaction as the change: action, key id, plan before and after, actor, reason, instant. Audit records MUST NOT contain the secret, the MAC or a client IP address. Unit
SEC-045 Audit records MUST be append-only for the API's own role and retained for audit.retention_days. Security

7. Abuse resistance

ID Requirement Verification
SEC-050 Validated keys MAY be cached for auth.key_cache_ttl; concurrent first requests for one key MUST cause a single lookup. Failed lookups MUST be cached for auth.negative_cache_ttl to blunt random-key floods. Unit
SEC-051 A per-IP limit MUST apply before a key is known (RATE-001). Load
SEC-052 Repeated authentication failures from one address MUST be limited by auth.failure_limit per window and answered with 429 rate-limited. Load

8. Later

OAuth 2.1 client credentials MAY be added for enterprise integrations once the specification is final; API keys remain supported. Mutual TLS is not planned.

Home

About

Design

Data Model

Technical specification

Testing

Engineering

Technology choice

Reference

Clone this wiki locally