Secondary web services: standardize a minimal private/public access property #599

Summary

Following up on the discussion in #85, #120, and #414: this issue proposes a narrow, additive extension that gives secondary web services (/services) a portable way to declare whether they require an openEO Bearer token, without attempting to solve sharing/permissions more broadly.

The gap

A secondary web service exists specifically to be consumed by clients that are not openEO clients like QGIS, Leaflet, a browser <img> or <iframe>, a WMTS/WMS-aware GIS tool. Today:

• Every /services* management endpoint (POST, GET, PATCH, DELETE /services/{service_id}, GET /services/{service_id}/logs) is unconditionally security: [Bearer: []].
• service.url (the actual tile/WMTS/WMS endpoint) is explicitly allowed to live outside the API and its auth is unspecified by the spec ("Does not necessarily need to be located within the API").
• There is no public, visibility, scope, or access property anywhere on the service object, or on any other resource, to let a back-end declare that a given service (and its metadata) is intentionally reachable without a token.

The result: every back-end that wants to support anonymous consumption of a service invents its own convention. No client can be written portably.

Proposal

Add an optional top-level access property to the service object:

Changes, all additive:

• service.access: string, enum ["private", "public"], optional, default private.
• POST /services, PATCH /services/{service_id}: accept access in the request body.
• GET /services/{service_id}: security: [{}, Bearer: []] when the extension is declared, mirroring the pattern already used by GET /service_types. Anonymous request → 200 when access: "public", 401 otherwise. Back-ends MAY redact budget, costs, usage, and plan from anonymous responses.
• service.url: for access: "public", MUST be reachable without openEO authentication (already implied by the existing "does not necessarily need to be located within the API" language).
• Services with access: "public" SHOULD carry a canonical link (reusing the existing relation from Link rel type for public sharing of UDP #405/"Canonical" links #408), so the "reachable without a token" fact is expressible in vocabulary clients already understand.

Explicitly out of scope

• Group/user-level ACLs (e.g. share with specific named users). Not proposed here because openEO has no portable way to resolve a user identity across back-ends (Introduce "service account" or user group concept #523 was closed without resolution). That belongs with the broader permissions work in Allow more fine-grained access permissions #414.
• Whether GET /services (the list endpoint) surfaces other users' public services. That would change existing behavior (today's list is owner-scoped), which extensions are not permitted to do. Left for a separate discussion if there's appetite for it.
• Billing semantics. The spec already notes costs for shared services are typically paid by the owner; budget and enabled remain the existing cost/kill-switch controls. This proposal adds no new billing behavior.
• Rate limiting / abuse mitigation for anonymous compute. Back-ends MAY throttle; this is an operational concern, not a spec concern, and enabled: false remains the kill switch.

Prior art / related discussion

• Sharing resources #85 — "Sharing resources" (asks "Are web services always public?", labeled extension)
• Extensibility of the API #120 — "Extensibility of the API" (lists sharing as an extension candidate)
• Allow more fine-grained access permissions #414 — "Allow more fine-grained access permissions" (where group/user ACLs belong)
• Link rel type for public sharing of UDP #405 / "Canonical" links #408 — the canonical link relation, the closest existing "reachable without Bearer auth" primitive
• Introduce "service account" or user group concept #523 — service account / user group concept, closed without resolution (why user-level ACLs aren't proposed here)

Next step

If there's interest, we'll follow up with a PR adding extensions/service-access/README.md, in the same shape as the existing federation, workspaces, commercial-data, processing-parameters, and remote-process-definition extensions (conformance class https://api.openeo.org/extensions/service-access/0.1.0, stability experimental).