Roles and permissions in Harmony

This page is for workspace administrators, integration leads, and support staff who need to manage access in Harmony. It explains workspace roles and permissions, API token scopes for (third party) integrations, and touch point codes for shared devices.

Scopes and roles

A scope is a single permission, such as "view master data" or "create and update
locations". Each is either a read or a write permission. Every API
endpoint declares the scope it requires, and a request without that scope is rejected.

A role is a predefined bundle of scopes. People are assigned roles, not scopes.

Roles are not additive. A membership carries exactly one role, and Harmony has no team
construct, so there is no mechanism by which permissions accumulate. Individual scopes
are assignable in one place only: API tokens. A token can therefore be scoped more
narrowly than any role. Touch points are a third case: they hold a fixed set that
cannot be edited.

Where a role applies

A role is a property of a membership rather than of a user account. One user may be an
Owner of one workspace, a Maintainer of a second, and have no membership of a third.
Role changes apply only to the workspace in which they are made.

flowchart LR
    U(["One user account"])
    U -- "membership: Owner" --> A["Workspace A"]
    U -- "membership: Maintainer" --> B["Workspace B"]
    U ~~~ C["Workspace C<br/>no membership"]

    classDef noAccess stroke-dasharray:4 3
    class C noAccess

An Observer or Operator membership can also be limited to a subset of the workspace's
locations, in which case the role's permissions apply only to those locations. Use it
when an operator may only send data on behalf of their own site, or when an observer may
only see one location or a specific set of them.

The five roles

Harmony defines five roles. Observer, Maintainer, Admin and Owner form an ascending
hierarchy, each containing the permissions of the one below it. Operator does not fit
that hierarchy; it is a separate set of permissions.

flowchart LR
    Ob["Observer"] --> Ma["Maintainer"] --> Ad["Admin"] --> Ow["Owner"]
    Op["Operator<br/>separate scope set,<br/>not part of the hierarchy"]

    classDef aside stroke-dasharray:4 3
    class Op aside

A short description of each role is given below. For a more detailed overview of all permissions, see: Permission reference

Observer

Read-only. An Observer can see operational data but cannot change anything.

Use for people who report on operations rather than run them: supply chain analysts,
warehouse managers, and colleagues investigating a discrepancy. Observer is the default
role for new invitations and the appropriate starting point when the access a person
needs is not yet established.

Operator

The role for personnel performing scanning work at a read point, packing bench or gate.
It is scoped to carrying out an operational task rather than to reviewing one.

Operator is not a superset of Observer. It is a separate set of permissions that
deliberately omits most of Observer's reporting access, with the effect that an
Operator produces data without being able to review it afterwards. Consult the
permission reference rather than assuming an Operator can see whatever an Observer can.

Operators are also routed differently in the web application: authentication as an
Operator redirects to the Operator Hub rather than the full workspace interface.

Use for store and warehouse personnel performing counts, packing, goods-in and
goods-out, and for fixed tablets at a tunnel or gate.

Maintainer

Maintainers can edit workspace configuration, locations, read points and readers, and
inspect hook and location logs. The role is mainly used by internal staff and support
engineers.

Admin

Operational control of the workspace, covering members, credentials, and
integrations. Admin holds everything except the commercial settings reserved for Owner
and the Owner role itself, which an Admin can neither grant nor modify.

Use for the person who runs the workspace: integration lead, rollout project manager,
or the IT contact responsible for issuing API credentials.

Owner

Unrestricted access, including the commercial settings and the Owner role itself. Nedap recommends at
least two Owners per workspace so that account control survives personnel changes.

Use for the party commercially and organizationally accountable for the workspace.

Touch points

A touch point is a screen or handheld paired to a single read point: a tablet at a
packing bench, a handheld at goods-in, the display beside a tunnel. It is not a user
account and has no role. It gets its own token, tied to one read point, with a fixed set
of permissions.

This section covers what a touch point may do. For the device-side setup, including
generating the code and adding the touch point to an iPad home screen, see
Run as Touchpoint.

Pairing with a code

Pairing runs through a one-time code, so nobody has to put Harmony credentials on the
device.

1. Someone with "Associate and configure touch points" (Maintainer and up) generates a
   code for a read point.
2. The code is entered on the device.
3. Harmony issues the device a token and records it against the read point.

What the code is:

• Nine characters, lowercase letters and digits, from a cryptographic random generator.
• Valid for 72 hours from creation.
• Single use. Redeeming it deletes it.
• One touch point per read point. Generating a second code for a read point that is
  already paired returns a conflict, and so does redeeming one.
• Redemption is unauthenticated, so the code alone is enough. Each attempt is delayed by
  one second to slow down guessing.
• Expired codes are removed automatically seven days after they lapse.

This is what makes it workable for external users. You can send someone a code, or read
it out over the phone, and they can bring a device online without an account, without a
password, and without you issuing an API token.

What a touch point may do

The token itself carries no scopes. Every request is checked against a fixed allow-list
of 18 scopes, shown in the Touch point column of the permission reference. In practice it
covers running the station: triggering reads, capturing and querying EPCIS events,
working with documents, requesting serial numbers, read access to master data and
locations, and the iD Cloud API.

A touch point is close to Operator but is not the same set, and neither contains the
other. They share 11 permissions. An Operator additionally sees read points, read point
actions and associated readers, none of which a touch point can list. A touch point
additionally queries EPCIS events and sees EPC status, device state, device observations
and location maps, none of which an Operator has. Only Admin and Owner hold everything a
touch point does.

The list is not configurable. A touch point cannot be widened or narrowed per device,
and a code cannot hand out a subset of it. Every touch point in every workspace gets the
same 18 permissions, so a read point is the only thing that scopes a device down.

Ending access

A touch point holds "Disassociate a touch point", so it can unpair itself. Anyone with
that permission can also do it from Harmony, which clears the token from the read point
and, for a paired native device, releases the reader.

The token is issued with a nine-year expiry, the same as an API token. Disassociation is
what ends access, not expiry.

Permission reference

Which roles hold which permission. A filled bullet (●) means granted, an empty bullet
(○) not granted. The last column is not a role: it is the fixed permission set of a
touch point, listed here because it is the only way to compare it against the roles.

API tokens

API tokens authenticate machines and integrations. Only Admin and Owner may create
them, and each token is bound to one workspace.

Choosing scopes

The creation form takes individual scopes or whole categories. Sixteen categories are
available to tokens: EPCIS, EPC Status, EPC Device Observations, EPC Device State, EPC
TID Bindings, Consolidations, Documents, Read Points, Locations, Master Data, Readers,
Serialisation, Variables, Third Party, Integration (email), and hook jobs.

Some permissions are closed to tokens entirely, full-access tokens included, an overview of which scopes are allowed can be found below. The scope value is what appears in the API token form and in a token's scope claim. 39 of the 67 scopes can be granted to an API token (●); the rest are interface-only (○).

Lifetime and revocation

Token lifetime is fixed at nine years from creation and is not configurable. There is no
expiry field, no maximum-lifetime policy and no rotation reminder, so rotation is a
manual process the workspace administrator owns. Issuing several narrowly scoped tokens
rather than one broad one keeps the cost of rotating any single credential low.

Revocation is immediate. Every request checks the token against the revocation list. The
token value appears once, at creation, and later listings show only its final five
characters, so record it in a secrets manager straight away.