Repository navigation
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.
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.
| 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 |
| 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 |
| 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 |
| 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 |
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 --> [*]
| 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 |
| 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 |
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.
ViaFrei API: a public, keyed, read-only REST API to live German mobility data. Design phase; nothing on these pages is a measurement of a running service. Data on viafrei.de and in every API answer is attributed to its publishers under their licences.
About
Design
- Domain Model
- API Design
- Architecture Overview
- Security and Access Keys
- Rate Limits and Priority
- Performance and Caching
- Configuration
- Observability
Data Model
Technical specification
-
Technical Specification
- Interface
- Scope, Conventions and References
- Protocol
- Common Envelope
- Resource Model
- Endpoints, Places
- Endpoints, Roads
- Endpoints, Energy and Parking
- Endpoints, Public Transport and Accessibility
- Endpoints, Weather Risk, Driving Rules and Composed Features
- Service Endpoints
- Errors
- Authentication and Authorisation
- Rate Limiting, Quotas and Priority
- Data Licensing and Attribution
- Compatibility and Versioning
- OpenAPI Skeleton
- Quality
- Delivery and operations
- Interface
Testing
- Testing Strategy
- Testing and Quality (design summary)
Engineering
Technology choice
- Technology Evaluation
- Architecture: Go
- Architecture: Rust
- Architecture: TypeScript
- Stack Comparison
- Benchmark Plan
Reference