Skip to main content

Sharing & Permissions

Sharing grants other users and teams read access to a Dataset, optionally limited to filtered rows. Editing rights are not part of shares; they come from team roles (see the overview).

A share is one row per principal:

PropertyDescription
principalIdA username or team id
accessLevel2: sees the full data. 1: rows are limited to the share's saved filter when datasetFilterId is set
datasetFilterIdA saved filter whose query limits what level-1 principals see
restrictFieldsWhen true, hides the Dataset's field definitions from the shared principal (used with the tenant's field-level security setting)

GET /api/datasets/{id}/shares​

List shares for a Dataset. The response is a plain array; each entry combines the share with display info for the user or team (name/displayName, icon/color or email/avatar, and type: User or Team).

Authentication: Required

List sharesGET /api/datasets/admin:northwind-orders/shares
A plain array; each entry carries display info for the shared user or team.
Response · 200
[
  {
    "datasetId": "00000000-0000-4000-8000-000000000001",
    "principalId": "marketing",
    "accessLevel": 2,
    "datasetFilterId": null,
    "restrictFields": false,
    "id": "marketing",
    "teamId": "marketing",
    "name": "Marketing",
    "materialIcon": null,
    "icon": "fa-bullhorn",
    "color": "red",
    "username": null,
    "displayName": null,
    "email": null,
    "avatarUpdatedAt": null,
    "type": "Team"
  }
]
Captured from the API examples test suite; ids and timestamps are normalized.

GET /api/datasets/{id}/shares/{principalId}​

Get a single share. Answers 404 when the principal has no share.

Authentication: Required

Get one shareGET /api/datasets/admin:northwind-orders/shares/everett
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/shares/everett"
    }
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "principalId": "everett",
  "datasetFilterId": "00000000-0000-4000-8000-000000000003",
  "restrictFields": false,
  "accessLevel": 1,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z"
}
Captured from the API examples test suite; ids and timestamps are normalized.

PUT /api/datasets/{id}/shares/{principalId}​

Create or update a share (upsert).

Authentication: Required

Permission: dataset:share (superuser, or Publisher and above on the owning team; user-owned Datasets can only be shared by a superuser)

Request Body:

FieldTypeRequiredDescription
accessLevelintegerNoMinimum 1 (default). 2 = full data, 1 = filtered by datasetFilterId. To remove access use DELETE
datasetFilterIdstringNoSaved filter id limiting rows for level-1 access; null clears it
restrictFieldsbooleanNoHide field definitions from this principal
Share a Dataset with a teamPUT /api/datasets/admin:northwind-orders/shares/marketing
principalId is a username or team id. accessLevel 2 grants the full data; accessLevel 1 limits rows to the share's saved filter (datasetFilterId) when one is set. PUT upserts: repeat it to change a share.
Request body
{
  "accessLevel": 2
}
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/shares/marketing"
    }
  },
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000001",
  "datasetId": "00000000-0000-4000-8000-000000000002",
  "principalId": "marketing",
  "accessLevel": 2,
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "_altid": null,
  "datasetFilterId": null,
  "restrictFields": false
}
Captured from the API examples test suite; ids and timestamps are normalized.
Share with a row filterPUT /api/datasets/admin:northwind-orders/shares/everett
everett sees only the rows matching the USA Orders filter. restrictFields: true additionally hides the field definitions from the shared principal (used with tenant field-level security).
Request body
{
  "accessLevel": 1,
  "datasetFilterId": "00000000-0000-4000-8000-000000000001"
}
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/shares/everett"
    }
  },
  "tenant": "acme",
  "id": "00000000-0000-4000-8000-000000000002",
  "datasetId": "00000000-0000-4000-8000-000000000003",
  "principalId": "everett",
  "accessLevel": 1,
  "datasetFilterId": "00000000-0000-4000-8000-000000000001",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "createdAt": "2026-01-15T16:20:00.000Z",
  "_altid": null,
  "restrictFields": false
}
Captured from the API examples test suite; ids and timestamps are normalized.

A share also notifies the recipient via the activity feed.

DELETE /api/datasets/{id}/shares/{principalId}​

Revoke a share.

Authentication: Required

Permission: dataset:share (same rule as PUT)

Revoke a shareDELETE /api/datasets/admin:northwind-orders/shares/everett
Responds 200 with an empty body.
Response · 200 · no body
Captured from the API examples test suite; ids and timestamps are normalized.

Behavior:

  • Removes the share row; the principal keeps any access they have through ownership or team membership
  • Responds 200 with an empty body

GET /api/datasets/{id}/permissions​

Get your resolved permission flags for the Dataset: the same permissions object every Dataset response embeds, as a standalone call.

Authentication: Required

Get my permissions on a DatasetGET /api/datasets/admin:northwind-orders/permissions
The same flags every Dataset response embeds, as a standalone call.
Response · 200
{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/admin%3Anorthwind-orders/permissions"
    }
  },
  "edit": true,
  "share": true,
  "delete": true,
  "write": true,
  "addVisual": true,
  "deleteVisual": true,
  "changeOwner": true,
  "copy": true,
  "rename": true,
  "refresh": true,
  "modifyFlows": true,
  "replaceFile": true,
  "modifySettings": true,
  "createDataView": true,
  "assignTags": true,
  "createFilter": true,
  "scriptFields": true,
  "setIndex": false
}
Captured from the API examples test suite; ids and timestamps are normalized.

There is no read flag: if you can address the Dataset at all, you can read it; otherwise every route answers 404.

Server-side enforcement

Share filters are enforced in every search the server runs for the shared user. Don't rely on client-side filtering for sensitive rows, but do note that a level-1 share without a datasetFilterId behaves like level 2.