Skip to main content
Version: v5.3

Permissions and namespaces

Every Notification Service resource except a device belongs to a single namespace, set when the resource is created. The namespace decides which permissions apply to the resource. To act on a resource, you need the matching permission in every namespace the request touches.

The Notification Service checks permissions against the Passport Service. Each check names an IRN, the action you want to perform and the namespaces the request acts on. The IRN depends on the request:

  • A list checks notificationsvc:<resource type>:*.
  • A create checks notificationsvc:<resource type>:{id}, with the ID the new resource is about to get.
  • A request that names a resource by ID checks notificationsvc:<resource type>:{id}, in the namespaces stored on that resource.

A grant on notificationsvc:<resource type>:* covers all three.

The namespace filter​

The nsfilter query parameter names the namespaces a request acts within. Repeat the parameter, or separate values with commas, to name more than one.

Spell the parameter in lowercase. A request that sends nsFilter is ignored, and the service treats the request as though it named no namespace at all.

nsfilter supplies a default rather than a boundary. The rules differ by operation:

  • A query that names no namespaces runs against the namespaces in the filter.
  • A create that names no namespaces places the new resource in the namespaces in the filter.
  • A query, create, update, or delete that names a namespace outside the filter fails with HTTP 403.
  • A request that refers to a group, template, sender or authorization stored outside the filter fails with HTTP 403.
  • A read by ID is never bounded by the filter, because the request names the resource outright. It needs no nsfilter, and it does not require the Platform Manager role: the namespaces come from the stored resource.

Requests that name no namespace​

A request that selects resources — a list, or a create — and names no namespace, either directly or through nsfilter, requires the Platform Manager role. The service cannot scope the permission check without a namespace, so it checks for the role instead.

A request that names a resource by ID is not affected. It takes its namespaces from the stored resource, so it is checked against those and never falls back to the role.

This catches people out. To list triggers as a normal user, send nsfilter. Omit it and the request fails with HTTP 403 rather than returning every trigger you can read.

The same rule applies to a resource stored with no namespaces. Only a Platform Manager can read or write it.

Platform Manager​

A Platform Manager skips the detailed permission check. The service confirms the role and allows the request, in any namespace.

A Platform Manager also skips the ownership check that applies to devices and to the notification log.

Namespaces do not restrict a Platform Manager anywhere, including in a trigger's event filters. A Platform Manager can create an event trigger whose filters name no namespace, and that trigger matches events in every namespace. Every other user must name a namespace in the filter.

Trigger event filters​

A trigger's event filters are unrelated to nsfilter. Event filters decide which events fire the trigger. nsfilter decides which namespaces the request acts within. The two are independent, and a trigger uses both.

When you create or update an event trigger, the service checks your permission in the namespaces named by the event filter as well as in the trigger's own namespaces. An event filter that names no namespace requires the Platform Manager role.

For more information on triggers, see the Triggers page.

Devices​

Devices work differently from every other resource in the Notification Service. A device has no namespace, and the service runs no permission check against the Passport Service.

Instead, the service checks ownership. You identify the owner through owner.irn, in the form passportsvc:user:<user id>.

  • You can create, update, and delete only devices you own.
  • You can read devices owned by other members of your organization.
  • A Platform Manager can act on any user's devices.

Because devices have no namespace, nsfilter does not scope a device request.

Permissions by resource​

The following table lists the action you need for each operation, on the IRN described at the top of this page and in the namespaces the request acts on.

Resource typeListCreateRead by IDUpdate or patchDelete
triggerREADCREATEREADEDITDELETE
subscriptionREADCREATEREADEDITDELETE
groupREADCREATEREADEDITDELETE
senderREADCREATEREADEDITDELETE
templateREADCREATEREADEDITDELETE
authorizationREADCREATEREADEDITDELETE
notificationREADNot supportedNot supportedNot supportedNot supported
DeviceNo permission check. See Devices.

The update action is spelled EDIT. There is no UPDATE action.

Permissions on referenced resources​

A trigger references groups, templates, and senders. A subscription references a group and an authorization. A sender references templates.

To reference a resource, you need some permission on it. Any action you hold satisfies the check, so holding READ is enough to attach a template to a sender.

Assigning a script permission profile to a trigger is stricter. You need the ASSIGN action on passportsvc:permission_profile in the trigger's namespaces. Without it, the create or update fails with HTTP 403.

The notification log​

Listing notifications requires both the READ action on notificationsvc:notification:* and an ownership check. Name the owner through owner.irn in the query. A query that names no owner requires the Platform Manager role.

The trigger statistics endpoints read the same data without the ownership check, so a user holding READ in the namespace can read per-trigger counts without being able to list the notifications themselves.

REST API reference​

For the permissions each endpoint needs, see the REST API pages: