Data access, permissions, and terms

Four blocks of the manifest disclose what an app does with data, who in the team may operate it, what it unlocks in the portal, and which terms an organization agrees to: dataAccess, permissions, unlocks with connects, and legal. For each block, the tables give the format, limits, and the effect in the portal.

Four blocks, four questions#

The blocks are deliberately separate: permissions describes who in the team may operate the app, not what the app accesses. The portal tells the organization this at the permissions of the app: “They control who in your team may operate the app.” What the app accesses is shown separately under Data & access.

dataAccess#

If the block is missing, the most restrictive reading applies: the app reads nothing, fetches nothing, and keeps its own data on uninstalling. It is therefore needed only where there is something to say.

A fifth card appears in the portal block but does not come from this block. Under Data & access, the portal lists the manifest’s resources before the four cards, the app’s own data areas that it creates for the organization, labeled Creates for you (see The manifest). The separation is intentional: resources says what is added, and dataAccess says what happens to what already exists. The store entry’s action card counts the areas as Own data.

Two rules connect the block to the code:

• No access without a declaration. Only if reads names a data set does the platform bind the token APP_TENANT_DATA to the backend (see Backend: resolvers, fetchers, and jobs). If a class obtains the token without the manifest naming a data set, startup aborts with a plain-text message that names the missing line. player-location also binds the token: the location OF the display does arrive in the context of the widget resolver (see below), but a fixed, chosen location arrives through location() of this token. location-hours without player-location or fleet-locations also aborts startup, because opening hours belong to a location that the app would then not see.
• No invented write capability. Every entry under writes must appear in the platform’s catalog. The catalog is empty today, so the platform rejects every declared write capability, and that is the right disclosure: there are none.

An example from the weather app: it reads the organization details (for the language in which weather conditions and weekdays are labeled) and the display’s location, and it reaches an external service. The place comes from the widget configuration, either a fixed place or the display’s location.

dataAccess: {
  reads: ['tenant-profile', 'player-location'],
  external: [
    {
      name: 'OpenWeather',
      purpose: 'Wir holen Wetterlage und Vorhersage für den gewählten Ort oder den Standort des Displays.',
      sends: 'Nur die auf etwa einen Kilometer gerundeten Koordinaten des gewählten Orts oder des Standorts, an dem das Display steht.',
    },
  ],
},

Anyone who fetches an address that a user entered in the portal describes it as a service with a descriptive name (the RSS app calls it “The entered feed address”, the calendar app “The entered ICS address”) and fetches it in the backend only through APP_GUARDED_FETCH.

The location of the display: player-location#

A scene often runs in all branches of an organization. With player-location, a widget shows each display’s own place, such as the weather outside the door or the local time, without anyone maintaining a scene per branch. The location is whatever the organization has stored as the location for the display in the portal.

It does not come through APP_TENANT_DATA but in the widget resolver’s context as ctx.location, because only there is it known which display is being resolved for:

The coordinates come from geocoding the address and are accurate to the building. Anyone who sends them to an external service rounds them to what the purpose needs and says so in sends and in the terms: the weather app sends two decimal places, about a kilometer, the same cell as its cache key.

A resolver has to distinguish three states:

If player-location is added with a new version, the version requires the organization’s consent like any new data access (Update waiting). Until it is accepted, ctx.location is absent.

For null, the widget needs a way out, such as a fallback place from its configuration or a placeholder with a notice, never an empty widget. The weather app uses the fallback place for a location without coordinates as well.

A fixed, chosen location of the organization itself, such as a substitute location for displays without a location, is read by the backend with APP_TENANT_DATA.location(tenantId, locationId) in the same shape. An identifier from another organization yields null. The preview in the editor resolves for a specific display when it sends playerId along (POST /v1/widget-data/preview). In tests, mockWidgetResolverContext({ location: mockWidgetLocation() }) from @szenera/apps-sdk/testing sets a location, and { location: null } sets the empty case.

Opening hours: location-hours#

Opening hours are master data of the location. The organization maintains them in the portal at the location (tab Opening hours), through PATCH /v1/locations/{id}, or with the MCP tool set_location_opening_hours, and every app that shows them reads the same ones. The area is separate from player-location because opening hours are not a place specification: an app that needs only the place does not get them, and a consent of its own stays understandable.

With location-hours, every location that the app reads (ctx.location and location(), and with fleet-locations also locations()) additionally carries hours:

hours is absent without the area or without consent, and null means the app may read, but no hours are maintained at the location. What applies on a given day is computed by openingDayOf from @szenera/contracts/fleet with the precedence special day over public holiday (closed) over weekly hours. If the organization changes the hours, the federal state, or the time zone, the platform rebuilds the location’s displays. The app itself handles the change of day and the end of a window through the validUntil of its resolver.

dataAccess: {
  reads: ['player-location', 'location-hours'],
},

In tests, mockWidgetLocation({ hours: … }) sets the hours and mockWidgetLocation({ hours: null }) the location without hours.

All locations: fleet-locations#

A fetch that must know in advance for which places it retrieves data reads the directory of locations: APP_TENANT_DATA.locations(tenantId) returns all of the organization’s locations ordered by name, with the full address (street, postalCode, city, countryCode), coordinates, and time zone, and with location-hours including hours. A resolver may not reach outside, so a job needs the places in advance, the Pharmacies on duty app the postal codes, for example. Anyone who sends the address to an external service states in dataAccess.external exactly what goes out.

In tests, createMockAppContainer({ locationsMock: [...] }) supplies the locations for location() and locations().

permissions#

The installation enters every permission into the organization’s permission catalog. Two lists, the same shape:

Each entry is a quartet:

The helper definePermission(key) only checks the format of a key and returns it unchanged. The bundled apps write the quartets directly into the manifest.

New permissions in a new version are not adopted silently by the platform: as soon as the version is published as stable, the installation moves to Update waiting, the app’s widgets cannot be inserted in the scene editor, and the app’s Update tab shows the added permissions with Accept and Decline. A call that uses the app beforehand fails with Grant.PendingReacceptance (HTTP 409), and a consent to a different manifest version fails with App.ManifestHashMismatch (HTTP 409).

unlocks and connects#

An app does not have to bring a surface. unlocks and connects describe the second purpose of an app: not delivering something but unlocking something. The feature lives in the platform, and the app is the gate in front of it.

A key that is not in the catalog keeps the app from loading, because otherwise an app could promise a feature or connection with nothing behind it. Both fields are omitted rather than set empty: an empty field would shift the canonical hash of every existing version.

The two gate apps show the patterns: video-wall declares unlocks: ['video-walls'], and onedrive declares unlocks: ['library-places'] and connects: ['microsoft-graph']. The store entry shows the unlocking in the Data & access tab under Unlocks in the portal. An app that only unlocks a core feature of the platform does not appear in the store as an app: video-wall appears there as the tile Core feature · Video wall (coreFeatures of the overview) and is missing from “My apps.”

legal#

Apps with the same legal topic point to the same sheet. The bundled apps use seven groups:

clock, countdown, countup, world-clock, word-clock, and video-wall remain without legal. The Opening hours app does show the organization’s own entries, but the platform computes the public holidays, and its terms cover that.

A new version of the terms, meaning a different disclaimerKey, makes a release subject to consent: as soon as the new version is published as stable, the installation moves to Update waiting, exactly as with new permissions. Anyone who changes the substance of the notice therefore bumps the key, in the same pass as the short summary, the full text, and the app version. The platform silently adopts a reworded short summary under the same key. A manifest change without a version bump does not reach existing installations.

Query the state of an installation#

An organization reads what has become of the manifest, permissions, and terms through two routes for its own installations. Both require a credential of the organization but no permission of their own: a valid sign-in suffices, and an API key reaches them regardless of which permissions are in its scope. An operator credential does not reach them, because both always answer about exactly one organization and reject a credential without an organization with 403 Permission.Denied.

pendingManifestHash is the machine-readable form of Update waiting: if a value is there, a new version requires consent, and status reports pending-reacceptance. Until the decision, the installation keeps running in its current version. GET /v1/me/apps/updates collects the installations that are waiting for it (with state: "pending", and next to them offers of higher versions with state: "offer"). For each app, GET /v1/me/apps/{appId}/update delivers the decision in plain text: version from and to, reasons, new and removed permissions and data accesses, terms before and after, the deadline, and whether declining is still possible. Accepting is done with POST /v1/me/apps/{appId}/update/accept and declining with POST /v1/me/apps/{appId}/update/reject, both with the manifestHash of the version the update leads to and the permission marketplace.app.accept. A decline holds until the next higher version.

curl -sS "$SZENERA_API/v1/me/apps?locale=en-US" \
  -H "Authorization: Bearer $SZENERA_API_KEY"

The consent history is the record against which a changed version can be checked: each entry records which manifest hash was consented to, with which permissions and when, and whether a person did so or the platform adopted it automatically because neither permissions nor terms had moved.

What the organization sees#

The installation dialog carries the subtitle “Review what the app does with your data, then confirm the installation.” It shows the Data & access block, below it lists the permissions as Roles & permissions with their count, shows the short summary of the terms under Important note, links the full text as The app’s full terms, and requires the checkbox I have read the permissions and the app’s terms and agree to them. before Install takes effect.

The same information is already in the app’s entry in the store, in the Data & access tab. Whoever is weighing whether they want the app at all should be able to read its terms before the click. The tab names which areas of its own the app creates (from resources), which data sets it reads, what it adds, which connections it keeps to the outside and what is transferred in the process, and what happens to its data on uninstalling. Below that come Privacy with the recipients from dataAccess.external and the short summary of the terms with the link to the full text, which the portal sets from legal.termsPath. What the manifest leaves out, the portal states explicitly (“This app does not access any of your existing data.”) instead of omitting the card.

GET /v1/me/apps/store/{appId} delivers the entry as StoreEntryView, fully decided: the app’s situation for the organization, exactly one action, and the reason with its numbers. The portal forms the sentences for it, and calculation happens only on the server.

The handbook describes the organization’s view of installing, permissions, and consent: Apps in the handbook.

Related#

• The manifest — the four blocks in the context of all fields.
• Configure widgets — what the widget catalog reveals about a widget’s configuration, and how a client checks it.
• What is an app, and how does it get onto a display? — the states of an installation in the lifecycle.
• Apps in the handbook — the organization’s view.