Repository navigation
Security and Access Keys
This page describes how callers are identified, what they may read, and how keys are protected through their whole life. Everything here is design; see Project Status.
vf_live_<key id>_<secret><checksum>
| Part | Purpose |
|---|---|
vf_live_ / vf_test_ prefix |
Distinguishes production keys from keys for the fixture-backed test instance, and lets secret scanners (including GitHub's) find leaked keys. The prefixes are configurable. |
| Key id | Short, public, base62. Appears in logs, usage reports and audit records. |
| Secret | 32 random bytes from a cryptographically secure generator, base62-encoded. Shown once, at issue time. |
| Checksum | A short checksum (GitHub-token style) that rejects typos without a database lookup. |
- Only a MAC of the secret is stored: HMAC-SHA-256 with a server-side pepper. A fast MAC is the right choice for high-entropy random secrets; a slow password hash would only burn CPU.
- The pepper comes from the environment or a secret file, never from the database. A previous pepper can be configured during pepper rotation; a key that matches under the old pepper is re-MACed.
- Comparisons run in constant time.
- Neither the secret nor the MAC is ever logged or returned.
-
Authorization: Bearer <key>orX-API-Key: <key>. - A key in the query string is refused with
400 key-in-query, because URLs end up in logs. - A missing key returns
401 missing-keywith aWWW-Authenticatechallenge.
A key belongs to a plan. Plans are rows in the access store, so they can be changed without a deployment; configuration only seeds the defaults.
| Plan attribute | Meaning |
|---|---|
| Tier |
critical, standard or bulk: the priority under load (see [[Rate Limits and Priority |
| Use class | consumer, non-commercial or commercial (wire values consumer, non_commercial, commercial): matched against each source's licence ([[Spec: Authentication and Authorisation |
| Rate and burst | the per-key token bucket |
| Daily and monthly quota | hard ceilings |
| History depth | how far back history endpoints may reach |
| Maximum page size | upper bound for limit
|
| Source families | which families the plan includes |
Scopes are feature families: places, roads, energy, parking, transit, accessibility, weather, rules, history. Every operation declares the scope it needs.
A source family is allowed for a request only if all of the following hold:
- the family is part of the key's plan;
- the plan's use class is permitted by that family's licence terms;
- any terms that require explicit acceptance have been accepted for this key;
- the family is not disabled by configuration.
flowchart LR
K[Key → plan] --> G{Licence gate}
T[Source terms register] --> G
A[Terms acceptance] --> G
D[Disabled families<br/>configuration] --> G
G -->|allowed families| Q[Query: only rows of<br/>allowed families are read]
Q --> R[Post-check every row]
R -->|violation| X[500 + alert metric]
R --> OK[Response with attribution]
- The allowed set is passed into the database query, so a forbidden row is never read at all.
- Every returned row is checked again (defence in depth). A violation is an internal error plus an alerting metric that must stay at zero.
- Default deny: a family is enabled for a use class only after its licence has been reviewed and signed off.
Illustrative cases (the reviewed licence matrix decides the real ones):
- a source licensed for consumer information only is served only to
consumerplans; - a source whose terms need explicit acceptance answers
403 terms-not-accepteduntil they are accepted; - share-alike sources are served with their condition note and a pointer to the share-alike export.
Keys are managed first through a command-line tool run by the operator, and later through a passkey-protected owner console. Every change writes an audit record in the same transaction.
| Action | Effect |
|---|---|
| Issue (plan, label, optional expiry) | prints the key once |
| Rotate (with an overlap window) | the old secret stays valid until the overlap ends, so clients can switch without downtime |
| Revoke (with a reason) | effective immediately: the running service is notified and evicts the key from its cache; at the latest after the key-cache lifetime |
| List, show, usage | read-only; never prints a secret |
Defaults (configurable): keys expire after a year; rotation overlap is seven days.
- Validated keys are cached for a short time; concurrent first requests for the same key cause one lookup.
- Failed lookups are cached briefly, which blunts floods of random keys.
- A per-IP limit applies before a key is known.
- The TLS edge applies a coarse per-IP ceiling and body-size limits in front of the service.
| Status | Type |
|---|---|
| 400 | key-in-query |
| 401 |
missing-key, invalid-key, key-expired, key-revoked
|
| 403 |
scope-denied, source-not-permitted, terms-not-accepted
|
- A redactor masks
Authorization,X-API-Keyand any string that looks like a ViaFrei key in every log sink. - Secret configuration values have a type that cannot be printed or serialised in clear.
- A test plants keys in a header, a query string and an error message, then searches every log output for them.
- The read role is read-only by default for every transaction, limited to the read contract, with a role-level statement timeout and a hard connection limit.
- Views that filter licensed rows are security barriers, owned by a role that cannot log in.
- Tests assert that the read role cannot see an internal object and that any write fails.
CodeQL, dependency review, Dependabot, secret scanning with push protection and a custom key pattern, signed images with provenance and SBOM, image vulnerability scanning, OpenSSF Scorecard, and private vulnerability reporting. See Development Process.
OAuth 2.1 client credentials may be added for enterprise integrations once the specification is final. API keys cover the need until then.
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