Updating permissions of a boundary

Multiple tenants can each register (see more) an alternative ‘instance’ of the same boundary geometry with their own associated metadata, and each can independently control how their data are shared. A user’s access to a boundary is therefore inferred from the union of any boundary references they have been granted access.

Prerequisites

Please note: write access to the API is available on request. Before granting access we will discuss with you how to ensure your users understand in which circumstances is relevant to create custom shapes. We will also assign you a unique source name to be used in input to the write endpoints.

Input

{“<tenant_id>":"<permission_value>"} string pairs encoded in a JSON object where:

• tenant_id: tenant ID to which the specific permission will be granted. Reserved keyword "all" meaning all tenants. One’s tenant_id can be discovered calling the GET /info endpoint;

• permission_value: one of the following:

  • discover: the specified tenant can discover the boundary in search results but no geometry information will be returned;

  • view: same as discover plus geometry will be returned;

  • manage: same as view plus the varda:permissions object will be returned in endpoint responses (where available) and permissions editing will be enabled.

NOTE: If no manage permission is specified, the current tenant will get manage permission to ensure that at least one tenant can manage the boundary reference.

Output

Same output payload of GET /boundary-references/{id} endpoint, a GeoJSON Polygon feature with:

• id: the UUID that identifies the boundary reference;

• geometry: the geometry associated to the boundary reference;

• properties: all the user plus Varda-defined properties provided at creation time.

Examples

To update the permissions to make a previously ‘private’ boundary openly accessible (this is also the default):

{ "all": "view" }

To share a private boundary with a specific tenant:

{ "org_k89yUHfBMoPfNeTB": "view" }

To delegate 'ownership' to manage permissions to another tenant (e.g. after loading data on their behalf):

{ "org_k89yUHfBMoPfNeTB": "manage" }

To make a boundary’s existence and relationships with other fields/boundaries discoverable to everyone, but disallow downloading the geometry to all except an auditor:

{ 
  "all": "discover",
  "org_k89yUHfBMoPfNeTB": "view" 
}

Contextual considerations

Both the boundary and the boundary reference have a geometry attached:

• the geometry attached to the boundary reference is exactly matching the geometry provided by the user in input;

• the geometry attached to the boundary is ‘normalized’, containing the smallest number of vertices capable of describing the same area of land

A boundary is always linked at least to one boundary reference. It can be linked to multiple boundary references if the boundary references are “described” by the same boundary geometry.

This is why a user/client that wants to update permissions of a boundary needs to specify the ID of the boundary reference; the ID of the boundary won’t be enough.

The update takes place only if the tenant requesting it has “manage“ permissions on the boundary reference, otherwise an error will be returned.

• Discoverability and visibility of a boundary reference depends entirely upon the permissions designated by the client, which are specified during the creation or updating of said boundary reference.

• Discoverability and visibility of a boundary is based on the least-restricted, or "highest-level" of permissions that have been designated for the associated boundary references.

It is also important to understand that permissions in input will override existing ones. Please refer to “Creation of public or private custom shapes in GFID“ for more details on permissions levels.